This is /home/cyd/emacs/doc/lispref/../../info/elisp, produced by
makeinfo version 4.13 from /home/cyd/emacs/doc/lispref/elisp.texi.

This is the `GNU Emacs Lisp Reference Manual' corresponding to Emacs
version 24.2.

Copyright (C) 1990-1996, 1998-2012 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with the Invariant Sections being "GNU General Public
     License," with the Front-Cover texts being "A GNU Manual," and
     with the Back-Cover Texts as in (a) below.  A copy of the license
     is included in the section entitled "GNU Free Documentation
     License."

     (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
     modify this GNU manual.  Buying copies from the FSF supports it in
     developing GNU and promoting software freedom."

INFO-DIR-SECTION GNU Emacs Lisp
START-INFO-DIR-ENTRY
* Elisp: (elisp).       The Emacs Lisp Reference Manual.
END-INFO-DIR-ENTRY


File: elisp,  Node: Network Processes,  Next: Network Options,  Up: Low-Level Network

37.17.1 `make-network-process'
------------------------------

The basic function for creating network connections and network servers
is `make-network-process'.  It can do either of those jobs, depending
on the arguments you give it.

 -- Function: make-network-process &rest args
     This function creates a network connection or server and returns
     the process object that represents it.  The arguments ARGS are a
     list of keyword/argument pairs.  Omitting a keyword is always
     equivalent to specifying it with value `nil', except for
     `:coding', `:filter-multibyte', and `:reuseaddr'.  Here are the
     meaningful keywords (those corresponding to network options are
     listed in the following section):

    :name NAME
          Use the string NAME as the process name.  It is modified if
          necessary to make it unique.

    :type TYPE
          Specify the communication type.  A value of `nil' specifies a
          stream connection (the default); `datagram' specifies a
          datagram connection; `seqpacket' specifies a "sequenced
          packet stream" connection.  Both connections and servers can
          be of these types.

    :server SERVER-FLAG
          If SERVER-FLAG is non-`nil', create a server.  Otherwise,
          create a connection.  For a stream type server, SERVER-FLAG
          may be an integer, which then specifies the length of the
          queue of pending connections to the server.  The default
          queue length is 5.

    :host HOST
          Specify the host to connect to.  HOST should be a host name or
          Internet address, as a string, or the symbol `local' to
          specify the local host.  If you specify HOST for a server, it
          must specify a valid address for the local host, and only
          clients connecting to that address will be accepted.

    :service SERVICE
          SERVICE specifies a port number to connect to; or, for a
          server, the port number to listen on.  It should be a service
          name that translates to a port number, or an integer
          specifying the port number directly.  For a server, it can
          also be `t', which means to let the system select an unused
          port number.

    :family FAMILY
          FAMILY specifies the address (and protocol) family for
          communication.  `nil' means determine the proper address
          family automatically for the given HOST and SERVICE.  `local'
          specifies a Unix socket, in which case HOST is ignored.
          `ipv4' and `ipv6' specify to use IPv4 and IPv6, respectively.

    :local LOCAL-ADDRESS
          For a server process, LOCAL-ADDRESS is the address to listen
          on.  It overrides FAMILY, HOST and SERVICE, so you might as
          well not specify them.

    :remote REMOTE-ADDRESS
          For a connection, REMOTE-ADDRESS is the address to connect to.
          It overrides FAMILY, HOST and SERVICE, so you might as well
          not specify them.

          For a datagram server, REMOTE-ADDRESS specifies the initial
          setting of the remote datagram address.

          The format of LOCAL-ADDRESS or REMOTE-ADDRESS depends on the
          address family:

             - An IPv4 address is represented as a five-element vector
               of four 8-bit integers and one 16-bit integer `[A B C D
               P]' corresponding to numeric IPv4 address A.B.C.D and
               port number P.

             - An IPv6 address is represented as a nine-element vector
               of 16-bit integers `[A B C D E F G H P]' corresponding
               to numeric IPv6 address A:B:C:D:E:F:G:H and port number
               P.

             - A local address is represented as a string, which
               specifies the address in the local address space.

             - An "unsupported family" address is represented by a cons
               `(F . AV)', where F is the family number and AV is a
               vector specifying the socket address using one element
               per address data byte.  Do not rely on this format in
               portable code, as it may depend on implementation
               defined constants, data sizes, and data structure
               alignment.

    :nowait BOOL
          If BOOL is non-`nil' for a stream connection, return without
          waiting for the connection to complete.  When the connection
          succeeds or fails, Emacs will call the sentinel function,
          with a second argument matching `"open"' (if successful) or
          `"failed"'.  The default is to block, so that
          `make-network-process' does not return until the connection
          has succeeded or failed.

    :stop STOPPED
          If STOPPED is non-`nil', start the network connection or
          server in the "stopped" state.

    :buffer BUFFER
          Use BUFFER as the process buffer.

    :coding CODING
          Use CODING as the coding system for this process.  To specify
          different coding systems for decoding data from the
          connection and for encoding data sent to it, specify
          `(DECODING .  ENCODING)' for CODING.

          If you don't specify this keyword at all, the default is to
          determine the coding systems from the data.

    :noquery QUERY-FLAG
          Initialize the process query flag to QUERY-FLAG.  *Note Query
          Before Exit::.

    :filter FILTER
          Initialize the process filter to FILTER.

    :filter-multibyte MULTIBYTE
          If MULTIBYTE is non-`nil', strings given to the process
          filter are multibyte, otherwise they are unibyte.  The
          default is the default value of `enable-multibyte-characters'.

    :sentinel SENTINEL
          Initialize the process sentinel to SENTINEL.

    :log LOG
          Initialize the log function of a server process to LOG.  The
          log function is called each time the server accepts a network
          connection from a client.  The arguments passed to the log
          function are SERVER, CONNECTION, and MESSAGE; where SERVER is
          the server process, CONNECTION is the new process for the
          connection, and MESSAGE is a string describing what has
          happened.

    :plist PLIST
          Initialize the process plist to PLIST.

     The original argument list, modified with the actual connection
     information, is available via the `process-contact' function.


File: elisp,  Node: Network Options,  Next: Network Feature Testing,  Prev: Network Processes,  Up: Low-Level Network

37.17.2 Network Options
-----------------------

The following network options can be specified when you create a
network process.  Except for `:reuseaddr', you can also set or modify
these options later, using `set-network-process-option'.

   For a server process, the options specified with
`make-network-process' are not inherited by the client connections, so
you will need to set the necessary options for each child connection as
it is created.

:bindtodevice DEVICE-NAME
     If DEVICE-NAME is a non-empty string identifying a network
     interface name (see `network-interface-list'), only handle packets
     received on that interface.  If DEVICE-NAME is `nil' (the
     default), handle packets received on any interface.

     Using this option may require special privileges on some systems.

:broadcast BROADCAST-FLAG
     If BROADCAST-FLAG is non-`nil' for a datagram process, the process
     will receive datagram packet sent to a broadcast address, and be
     able to send packets to a broadcast address.  This is ignored for
     a stream connection.

:dontroute DONTROUTE-FLAG
     If DONTROUTE-FLAG is non-`nil', the process can only send to hosts
     on the same network as the local host.

:keepalive KEEPALIVE-FLAG
     If KEEPALIVE-FLAG is non-`nil' for a stream connection, enable
     exchange of low-level keep-alive messages.

:linger LINGER-ARG
     If LINGER-ARG is non-`nil', wait for successful transmission of
     all queued packets on the connection before it is deleted (see
     `delete-process').  If LINGER-ARG is an integer, it specifies the
     maximum time in seconds to wait for queued packets to be sent
     before closing the connection.  The default is `nil', which means
     to discard unsent queued packets when the process is deleted.

:oobinline OOBINLINE-FLAG
     If OOBINLINE-FLAG is non-`nil' for a stream connection, receive
     out-of-band data in the normal data stream.  Otherwise, ignore
     out-of-band data.

:priority PRIORITY
     Set the priority for packets sent on this connection to the integer
     PRIORITY.  The interpretation of this number is protocol specific;
     such as setting the TOS (type of service) field on IP packets sent
     on this connection.  It may also have system dependent effects,
     such as selecting a specific output queue on the network interface.

:reuseaddr REUSEADDR-FLAG
     If REUSEADDR-FLAG is non-`nil' (the default) for a stream server
     process, allow this server to reuse a specific port number (see
     `:service'), unless another process on this host is already
     listening on that port.  If REUSEADDR-FLAG is `nil', there may be
     a period of time after the last use of that port (by any process
     on the host) where it is not possible to make a new server on that
     port.

 -- Function: set-network-process-option process option value &optional
          no-error
     This function sets or modifies a network option for network process
     PROCESS.  The accepted options and values are as for
     `make-network-process'.  If NO-ERROR is non-`nil', this function
     returns `nil' instead of signaling an error if OPTION is not a
     supported option.  If the function successfully completes, it
     returns `t'.

     The current setting of an option is available via the
     `process-contact' function.


File: elisp,  Node: Network Feature Testing,  Prev: Network Options,  Up: Low-Level Network

37.17.3 Testing Availability of Network Features
------------------------------------------------

To test for the availability of a given network feature, use `featurep'
like this:

     (featurep 'make-network-process '(KEYWORD VALUE))

The result of this form is `t' if it works to specify KEYWORD with
value VALUE in `make-network-process'.  Here are some of the
KEYWORD--VALUE pairs you can test in this way.

`(:nowait t)'
     Non-`nil' if non-blocking connect is supported.

`(:type datagram)'
     Non-`nil' if datagrams are supported.

`(:family local)'
     Non-`nil' if local (a.k.a. "UNIX domain") sockets are supported.

`(:family ipv6)'
     Non-`nil' if IPv6 is supported.

`(:service t)'
     Non-`nil' if the system can select the port for a server.

   To test for the availability of a given network option, use
`featurep' like this:

     (featurep 'make-network-process 'KEYWORD)

The accepted KEYWORD values are `:bindtodevice', etc.  For the complete
list, *note Network Options::.  This form returns non-`nil' if that
particular network option is supported by `make-network-process' (or
`set-network-process-option').


File: elisp,  Node: Misc Network,  Next: Serial Ports,  Prev: Low-Level Network,  Up: Processes

37.18 Misc Network Facilities
=============================

These additional functions are useful for creating and operating on
network connections.  Note that they are supported only on some systems.

 -- Function: network-interface-list
     This function returns a list describing the network interfaces of
     the machine you are using.  The value is an alist whose elements
     have the form `(NAME . ADDRESS)'.  ADDRESS has the same form as
     the LOCAL-ADDRESS and REMOTE-ADDRESS arguments to
     `make-network-process'.

 -- Function: network-interface-info ifname
     This function returns information about the network interface named
     IFNAME.  The value is a list of the form `(ADDR BCAST NETMASK
     HWADDR FLAGS)'.

    ADDR
          The Internet protocol address.

    BCAST
          The broadcast address.

    NETMASK
          The network mask.

    HWADDR
          The layer 2 address (Ethernet MAC address, for instance).

    FLAGS
          The current flags of the interface.

 -- Function: format-network-address address &optional omit-port
     This function converts the Lisp representation of a network
     address to a string.

     A five-element vector `[A B C D P]' represents an IPv4 address
     A.B.C.D and port number P.  `format-network-address' converts that
     to the string `"A.B.C.D:P"'.

     A nine-element vector `[A B C D E F G H P]' represents an IPv6
     address along with a port number.  `format-network-address'
     converts that to the string `"[A:B:C:D:E:F:G:H]:P"'.

     If the vector does not include the port number, P, or if OMIT-PORT
     is non-`nil', the result does not include the `:P' suffix.


File: elisp,  Node: Serial Ports,  Next: Byte Packing,  Prev: Misc Network,  Up: Processes

37.19 Communicating with Serial Ports
=====================================

Emacs can communicate with serial ports.  For interactive use, `M-x
serial-term' opens a terminal window.  In a Lisp program,
`make-serial-process' creates a process object.

   The serial port can be configured at run-time, without having to
close and re-open it.  The function `serial-process-configure' lets you
change the speed, bytesize, and other parameters.  In a terminal window
created by `serial-term', you can click on the mode line for
configuration.

   A serial connection is represented by a process object, which can be
used in a similar way to a subprocess or network process.  You can send
and receive data, and configure the serial port.  A serial process
object has no process ID, however, and you can't send signals to it,
and the status codes are different from other types of processes.
`delete-process' on the process object or `kill-buffer' on the process
buffer close the connection, but this does not affect the device
connected to the serial port.

   The function `process-type' returns the symbol `serial' for a
process object representing a serial port connection.

   Serial ports are available on GNU/Linux, Unix, and MS Windows
systems.

 -- Command: serial-term port speed
     Start a terminal-emulator for a serial port in a new buffer.  PORT
     is the name of the serial port to connect to.  For example, this
     could be `/dev/ttyS0' on Unix.  On MS Windows, this could be
     `COM1', or `\\.\COM10' (double the backslashes in Lisp strings).

     SPEED is the speed of the serial port in bits per second.  9600 is
     a common value.  The buffer is in Term mode; see *note Term Mode:
     (emacs)Term Mode, for the commands to use in that buffer.  You can
     change the speed and the configuration in the mode line menu.

 -- Function: make-serial-process &rest args
     This function creates a process and a buffer.  Arguments are
     specified as keyword/argument pairs.  Here's the list of the
     meaningful keywords, with the first two (PORT and SPEED) being
     mandatory:

    `:port PORT'
          This is the name of the serial port.  On Unix and GNU
          systems, this is a file name such as `/dev/ttyS0'.  On
          Windows, this could be `COM1', or `\\.\COM10' for ports
          higher than `COM9' (double the backslashes in Lisp strings).

    `:speed SPEED'
          The speed of the serial port in bits per second.  This
          function calls `serial-process-configure' to handle the
          speed; see the following documentation of that function for
          more details.

    `:name NAME'
          The name of the process.  If NAME is not given, PORT will
          serve as the process name as well.

    `:buffer BUFFER'
          The buffer to associate with the process.  The value can be
          either a buffer or a string that names a buffer.  Process
          output goes at the end of that buffer, unless you specify an
          output stream or filter function to handle the output.  If
          BUFFER is not given, the process buffer's name is taken from
          the value of the `:name' keyword.

    `:coding CODING'
          If CODING is a symbol, it specifies the coding system used for
          both reading and writing for this process.  If CODING is a
          cons `(DECODING . ENCODING)', DECODING is used for reading,
          and ENCODING is used for writing.  If not specified, the
          default is to determine the coding systems from the data
          itself.

    `:noquery QUERY-FLAG'
          Initialize the process query flag to QUERY-FLAG.  *Note Query
          Before Exit::.  The flags defaults to `nil' if unspecified.

    `:stop BOOL'
          Start process in the "stopped" state if BOOL is non-`nil'.
          In the stopped state, a serial process does not accept
          incoming data, but you can send outgoing data.  The stopped
          state is cleared by `continue-process' and set by
          `stop-process'.

    `:filter FILTER'
          Install FILTER as the process filter.

    `:sentinel SENTINEL'
          Install SENTINEL as the process sentinel.

    `:plist PLIST'
          Install PLIST as the initial plist of the process.

    `:bytesize'
    `:parity'
    `:stopbits'
    `:flowcontrol'
          These are handled by `serial-process-configure', which is
          called by `make-serial-process'.

     The original argument list, possibly modified by later
     configuration, is available via the function `process-contact'.

     Here is an example:

          (make-serial-process :port "/dev/ttyS0" :speed 9600)

 -- Function: serial-process-configure &rest args
     This functions configures a serial port connection.  Arguments are
     specified as keyword/argument pairs.  Attributes that are not given
     are re-initialized from the process's current configuration
     (available via the function `process-contact'), or set to
     reasonable default values.  The following arguments are defined:

    `:process PROCESS'
    `:name NAME'
    `:buffer BUFFER'
    `:port PORT'
          Any of these arguments can be given to identify the process
          that is to be configured.  If none of these arguments is
          given, the current buffer's process is used.

    `:speed SPEED'
          The speed of the serial port in bits per second, a.k.a. "baud
          rate".  The value can be any number, but most serial ports
          work only at a few defined values between 1200 and 115200,
          with 9600 being the most common value.  If SPEED is `nil',
          the function ignores all other arguments and does not
          configure the port.  This may be useful for special serial
          ports such as Bluetooth-to-serial converters, which can only
          be configured through `AT' commands sent through the
          connection.  The value of `nil' for SPEED is valid only for
          connections that were already opened by a previous call to
          `make-serial-process' or `serial-term'.

    `:bytesize BYTESIZE'
          The number of bits per byte, which can be 7 or 8.  If BYTESIZE
          is not given or `nil', it defaults to 8.

    `:parity PARITY'
          The value can be `nil' (don't use parity), the symbol `odd'
          (use odd parity), or the symbol `even' (use even parity).  If
          PARITY is not given, it defaults to no parity.

    `:stopbits STOPBITS'
          The number of stopbits used to terminate a transmission of
          each byte.  STOPBITS can be 1 or 2.  If STOPBITS is not given
          or `nil', it defaults to 1.

    `:flowcontrol FLOWCONTROL'
          The type of flow control to use for this connection, which is
          either `nil' (don't use flow control), the symbol `hw' (use
          RTS/CTS hardware flow control), or the symbol `sw' (use
          XON/XOFF software flow control).  If FLOWCONTROL is not
          given, it defaults to no flow control.

     Internally, `make-serial-process' calls `serial-process-configure'
     for the initial configuration of the serial port.


File: elisp,  Node: Byte Packing,  Prev: Serial Ports,  Up: Processes

37.20 Packing and Unpacking Byte Arrays
=======================================

This section describes how to pack and unpack arrays of bytes, usually
for binary network protocols.  These functions convert byte arrays to
alists, and vice versa.  The byte array can be represented as a unibyte
string or as a vector of integers, while the alist associates symbols
either with fixed-size objects or with recursive sub-alists.  To use
the functions referred to in this section, load the `bindat' library.

   Conversion from byte arrays to nested alists is also known as
"deserializing" or "unpacking", while going in the opposite direction
is also known as "serializing" or "packing".

* Menu:

* Bindat Spec::         Describing data layout.
* Bindat Functions::    Doing the unpacking and packing.
* Bindat Examples::     Samples of what bindat.el can do for you!


File: elisp,  Node: Bindat Spec,  Next: Bindat Functions,  Up: Byte Packing

37.20.1 Describing Data Layout
------------------------------

To control unpacking and packing, you write a "data layout
specification", a special nested list describing named and typed
"fields".  This specification controls the length of each field to be
processed, and how to pack or unpack it.  We normally keep bindat specs
in variables whose names end in `-bindat-spec'; that kind of name is
automatically recognized as "risky".

   A field's "type" describes the size (in bytes) of the object that
the field represents and, in the case of multibyte fields, how the
bytes are ordered within the field.  The two possible orderings are
"big endian" (also known as "network byte ordering") and "little
endian".  For instance, the number `#x23cd' (decimal 9165) in big
endian would be the two bytes `#x23' `#xcd'; and in little endian,
`#xcd' `#x23'.  Here are the possible type values:

`u8'
`byte'
     Unsigned byte, with length 1.

`u16'
`word'
`short'
     Unsigned integer in network byte order, with length 2.

`u24'
     Unsigned integer in network byte order, with length 3.

`u32'
`dword'
`long'
     Unsigned integer in network byte order, with length 4.  Note:
     These values may be limited by Emacs's integer implementation
     limits.

`u16r'
`u24r'
`u32r'
     Unsigned integer in little endian order, with length 2, 3 and 4,
     respectively.

`str LEN'
     String of length LEN.

`strz LEN'
     Zero-terminated string, in a fixed-size field with length LEN.

`vec LEN [TYPE]'
     Vector of LEN elements of type TYPE, defaulting to bytes.  The
     TYPE is any of the simple types above, or another vector specified
     as a list of the form `(vec LEN [TYPE])'.

`ip'
     Four-byte vector representing an Internet address.  For example:
     `[127 0 0 1]' for localhost.

`bits LEN'
     List of set bits in LEN bytes.  The bytes are taken in big endian
     order and the bits are numbered starting with `8 * LEN - 1' and
     ending with zero.  For example: `bits 2' unpacks `#x28' `#x1c' to
     `(2 3 4 11 13)' and `#x1c' `#x28' to `(3 5 10 11 12)'.

`(eval FORM)'
     FORM is a Lisp expression evaluated at the moment the field is
     unpacked or packed.  The result of the evaluation should be one of
     the above-listed type specifications.

   For a fixed-size field, the length LEN is given as an integer
specifying the number of bytes in the field.

   When the length of a field is not fixed, it typically depends on the
value of a preceding field.  In this case, the length LEN can be given
either as a list `(NAME ...)' identifying a "field name" in the format
specified for `bindat-get-field' below, or by an expression `(eval
FORM)' where FORM should evaluate to an integer, specifying the field
length.

   A field specification generally has the form `([NAME] HANDLER)',
where NAME is optional.  Don't use names that are symbols meaningful as
type specifications (above) or handler specifications (below), since
that would be ambiguous.  NAME can be a symbol or an expression `(eval
FORM)', in which case FORM should evaluate to a symbol.

   HANDLER describes how to unpack or pack the field and can be one of
the following:

`TYPE'
     Unpack/pack this field according to the type specification TYPE.

`eval FORM'
     Evaluate FORM, a Lisp expression, for side-effect only.  If the
     field name is specified, the value is bound to that field name.

`fill LEN'
     Skip LEN bytes.  In packing, this leaves them unchanged, which
     normally means they remain zero.  In unpacking, this means they
     are ignored.

`align LEN'
     Skip to the next multiple of LEN bytes.

`struct SPEC-NAME'
     Process SPEC-NAME as a sub-specification.  This describes a
     structure nested within another structure.

`union FORM (TAG SPEC)...'
     Evaluate FORM, a Lisp expression, find the first TAG that matches
     it, and process its associated data layout specification SPEC.
     Matching can occur in one of three ways:

        * If a TAG has the form `(eval EXPR)', evaluate EXPR with the
          variable `tag' dynamically bound to the value of FORM.  A
          non-`nil' result indicates a match.

        * TAG matches if it is `equal' to the value of FORM.

        * TAG matches unconditionally if it is `t'.

`repeat COUNT FIELD-SPECS...'
     Process the FIELD-SPECS recursively, in order, then repeat
     starting from the first one, processing all the specifications
     COUNT times overall.  The COUNT is given using the same formats as
     a field length--if an `eval' form is used, it is evaluated just
     once.  For correct operation, each specification in FIELD-SPECS
     must include a name.

   For the `(eval FORM)' forms used in a bindat specification, the FORM
can access and update these dynamically bound variables during
evaluation:

`last'
     Value of the last field processed.

`bindat-raw'
     The data as a byte array.

`bindat-idx'
     Current index (within `bindat-raw') for unpacking or packing.

`struct'
     The alist containing the structured data that have been unpacked so
     far, or the entire structure being packed.  You can use
     `bindat-get-field' to access specific fields of this structure.

`count'
`index'
     Inside a `repeat' block, these contain the maximum number of
     repetitions (as specified by the COUNT parameter), and the current
     repetition number (counting from 0).  Setting `count' to zero will
     terminate the inner-most repeat block after the current repetition
     has completed.


File: elisp,  Node: Bindat Functions,  Next: Bindat Examples,  Prev: Bindat Spec,  Up: Byte Packing

37.20.2 Functions to Unpack and Pack Bytes
------------------------------------------

In the following documentation, SPEC refers to a data layout
specification, `bindat-raw' to a byte array, and STRUCT to an alist
representing unpacked field data.

 -- Function: bindat-unpack spec bindat-raw &optional bindat-idx
     This function unpacks data from the unibyte string or byte array
     `bindat-raw' according to SPEC.  Normally, this starts unpacking
     at the beginning of the byte array, but if BINDAT-IDX is
     non-`nil', it specifies a zero-based starting position to use
     instead.

     The value is an alist or nested alist in which each element
     describes one unpacked field.

 -- Function: bindat-get-field struct &rest name
     This function selects a field's data from the nested alist STRUCT.
     Usually STRUCT was returned by `bindat-unpack'.  If NAME
     corresponds to just one argument, that means to extract a
     top-level field value.  Multiple NAME arguments specify repeated
     lookup of sub-structures.  An integer name acts as an array index.

     For example, if NAME is `(a b 2 c)', that means to find field `c'
     in the third element of subfield `b' of field `a'.  (This
     corresponds to `struct.a.b[2].c' in C.)

   Although packing and unpacking operations change the organization of
data (in memory), they preserve the data's "total length", which is the
sum of all the fields' lengths, in bytes.  This value is not generally
inherent in either the specification or alist alone; instead, both
pieces of information contribute to its calculation.  Likewise, the
length of a string or array being unpacked may be longer than the data's
total length as described by the specification.

 -- Function: bindat-length spec struct
     This function returns the total length of the data in STRUCT,
     according to SPEC.

 -- Function: bindat-pack spec struct &optional bindat-raw bindat-idx
     This function returns a byte array packed according to SPEC from
     the data in the alist STRUCT.  It normally creates and fills a new
     byte array starting at the beginning.  However, if BINDAT-RAW is
     non-`nil', it specifies a pre-allocated unibyte string or vector to
     pack into.  If BINDAT-IDX is non-`nil', it specifies the starting
     offset for packing into `bindat-raw'.

     When pre-allocating, you should make sure `(length BINDAT-RAW)'
     meets or exceeds the total length to avoid an out-of-range error.

 -- Function: bindat-ip-to-string ip
     Convert the Internet address vector IP to a string in the usual
     dotted notation.

          (bindat-ip-to-string [127 0 0 1])
               => "127.0.0.1"


File: elisp,  Node: Bindat Examples,  Prev: Bindat Functions,  Up: Byte Packing

37.20.3 Examples of Byte Unpacking and Packing
----------------------------------------------

Here is a complete example of byte unpacking and packing:

     (require 'bindat)

     (defvar fcookie-index-spec
       '((:version  u32)
         (:count    u32)
         (:longest  u32)
         (:shortest u32)
         (:flags    u32)
         (:delim    u8)
         (:ignored  fill 3)
         (:offset   repeat (:count) (:foo u32)))
       "Description of a fortune cookie index file's contents.")

     (defun fcookie (cookies &optional index)
       "Display a random fortune cookie from file COOKIES.
     Optional second arg INDEX specifies the associated index
     filename, by default \"COOKIES.dat\".  Display cookie text
     in buffer \"*Fortune Cookie: BASENAME*\", where BASENAME
     is COOKIES without the directory part."
       (interactive "fCookies file: ")
       (let* ((info (with-temp-buffer
                      (insert-file-contents-literally
                       (or index (concat cookies ".dat")))
                      (bindat-unpack fcookie-index-spec
                                     (buffer-string))))
              (sel (random (bindat-get-field info :count)))
              (beg (cdar (bindat-get-field info :offset sel)))
              (end (or (cdar (bindat-get-field info
                                               :offset (1+ sel)))
                       (nth 7 (file-attributes cookies)))))
         (switch-to-buffer
          (get-buffer-create
           (format "*Fortune Cookie: %s*"
                   (file-name-nondirectory cookies))))
         (erase-buffer)
         (insert-file-contents-literally
          cookies nil beg (- end 3))))

     (defun fcookie-create-index (cookies &optional index delim)
       "Scan file COOKIES, and write out its index file.
     Optional arg INDEX specifies the index filename, which by
     default is \"COOKIES.dat\".  Optional arg DELIM specifies the
     unibyte character that, when found on a line of its own in
     COOKIES, indicates the border between entries."
       (interactive "fCookies file: ")
       (setq delim (or delim ?%))
       (let ((delim-line (format "\n%c\n" delim))
             (count 0)
             (max 0)
             min p q len offsets)
         (unless (= 3 (string-bytes delim-line))
           (error "Delimiter cannot be represented in one byte"))
         (with-temp-buffer
           (insert-file-contents-literally cookies)
           (while (and (setq p (point))
                       (search-forward delim-line (point-max) t)
                       (setq len (- (point) 3 p)))
             (setq count (1+ count)
                   max (max max len)
                   min (min (or min max) len)
                   offsets (cons (1- p) offsets))))
         (with-temp-buffer
           (set-buffer-multibyte nil)
           (insert
            (bindat-pack
             fcookie-index-spec
             `((:version . 2)
               (:count . ,count)
               (:longest . ,max)
               (:shortest . ,min)
               (:flags . 0)
               (:delim . ,delim)
               (:offset . ,(mapcar (lambda (o)
                                     (list (cons :foo o)))
                                   (nreverse offsets))))))
           (let ((coding-system-for-write 'raw-text-unix))
             (write-file (or index (concat cookies ".dat")))))))

   The following is an example of defining and unpacking a complex
structure.  Consider the following C structures:

     struct header {
         unsigned long    dest_ip;
         unsigned long    src_ip;
         unsigned short   dest_port;
         unsigned short   src_port;
     };

     struct data {
         unsigned char    type;
         unsigned char    opcode;
         unsigned short   length;  /* in network byte order  */
         unsigned char    id[8];   /* null-terminated string  */
         unsigned char    data[/* (length + 3) & ~3 */];
     };

     struct packet {
         struct header    header;
         unsigned long    counters[2];  /* in little endian order  */
         unsigned char    items;
         unsigned char    filler[3];
         struct data      item[/* items */];

     };

   The corresponding data layout specification is:

     (setq header-spec
           '((dest-ip   ip)
             (src-ip    ip)
             (dest-port u16)
             (src-port  u16)))

     (setq data-spec
           '((type      u8)
             (opcode    u8)
             (length    u16)  ; network byte order
             (id        strz 8)
             (data      vec (length))
             (align     4)))

     (setq packet-spec
           '((header    struct header-spec)
             (counters  vec 2 u32r)   ; little endian order
             (items     u8)
             (fill      3)
             (item      repeat (items)
                        (struct data-spec))))

   A binary data representation is:

     (setq binary-data
           [ 192 168 1 100 192 168 1 101 01 28 21 32
             160 134 1 0 5 1 0 0 2 0 0 0
             2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0
             1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ])

   The corresponding decoded structure is:

     (setq decoded (bindat-unpack packet-spec binary-data))
          =>
     ((header
       (dest-ip   . [192 168 1 100])
       (src-ip    . [192 168 1 101])
       (dest-port . 284)
       (src-port  . 5408))
      (counters . [100000 261])
      (items . 2)
      (item ((data . [1 2 3 4 5])
             (id . "ABCDEF")
             (length . 5)
             (opcode . 3)
             (type . 2))
            ((data . [6 7 8 9 10 11 12])
             (id . "BCDEFG")
             (length . 7)
             (opcode . 4)
             (type . 1))))

   An example of fetching data from this structure:

     (bindat-get-field decoded 'item 1 'id)
          => "BCDEFG"


File: elisp,  Node: Display,  Next: System Interface,  Prev: Processes,  Up: Top

38 Emacs Display
****************

This chapter describes a number of features related to the display that
Emacs presents to the user.

* Menu:

* Refresh Screen::      Clearing the screen and redrawing everything on it.
* Forcing Redisplay::   Forcing redisplay.
* Truncation::          Folding or wrapping long text lines.
* The Echo Area::       Displaying messages at the bottom of the screen.
* Warnings::            Displaying warning messages for the user.
* Invisible Text::      Hiding part of the buffer text.
* Selective Display::   Hiding part of the buffer text (the old way).
* Temporary Displays::  Displays that go away automatically.
* Overlays::            Use overlays to highlight parts of the buffer.
* Width::               How wide a character or string is on the screen.
* Line Height::         Controlling the height of lines.
* Faces::               A face defines a graphics style for text characters:
                          font, colors, etc.
* Fringes::             Controlling window fringes.
* Scroll Bars::         Controlling vertical scroll bars.
* Display Property::    Enabling special display features.
* Images::              Displaying images in Emacs buffers.
* Buttons::             Adding clickable buttons to Emacs buffers.
* Abstract Display::    Emacs's Widget for Object Collections.
* Blinking::            How Emacs shows the matching open parenthesis.
* Character Display::   How Emacs displays individual characters.
* Beeping::             Audible signal to the user.
* Window Systems::      Which window system is being used.
* Bidirectional Display:: Display of bidirectional scripts, such as
                             Arabic and Farsi.


File: elisp,  Node: Refresh Screen,  Next: Forcing Redisplay,  Up: Display

38.1 Refreshing the Screen
==========================

The function `redraw-frame' clears and redisplays the entire contents
of a given frame (*note Frames::).  This is useful if the screen is
corrupted.

 -- Function: redraw-frame frame
     This function clears and redisplays frame FRAME.

   Even more powerful is `redraw-display':

 -- Command: redraw-display
     This function clears and redisplays all visible frames.

   In Emacs, processing user input takes priority over redisplay.  If
you call these functions when input is available, they don't redisplay
immediately, but the requested redisplay does happen eventually--after
all the input has been processed.

   On text terminals, suspending and resuming Emacs normally also
refreshes the screen.  Some terminal emulators record separate contents
for display-oriented programs such as Emacs and for ordinary sequential
display.  If you are using such a terminal, you might want to inhibit
the redisplay on resumption.

 -- User Option: no-redraw-on-reenter
     This variable controls whether Emacs redraws the entire screen
     after it has been suspended and resumed.  Non-`nil' means there is
     no need to redraw, `nil' means redrawing is needed.  The default
     is `nil'.


File: elisp,  Node: Forcing Redisplay,  Next: Truncation,  Prev: Refresh Screen,  Up: Display

38.2 Forcing Redisplay
======================

Emacs normally tries to redisplay the screen whenever it waits for
input.  With the following function, you can request an immediate
attempt to redisplay, in the middle of Lisp code, without actually
waiting for input.

 -- Function: redisplay &optional force
     This function tries immediately to redisplay.  The optional
     argument FORCE, if non-`nil', forces the redisplay to be performed,
     instead of being preempted, even if input is pending and the
     variable `redisplay-dont-pause' is `nil' (see below).  If
     `redisplay-dont-pause' is non-`nil' (the default), this function
     redisplays in any case, i.e. FORCE does nothing.

     The function returns `t' if it actually tried to redisplay, and
     `nil' otherwise.  A value of `t' does not mean that redisplay
     proceeded to completion; it could have been preempted by newly
     arriving input.

 -- Variable: redisplay-dont-pause
     If this variable is `nil', arriving input events preempt
     redisplay; Emacs avoids starting a redisplay, and stops any
     redisplay that is in progress, until the input has been processed.
     In particular, `(redisplay)' returns `nil' without actually
     redisplaying, if there is pending input.

     The default value is `t', which means that pending input does not
     preempt redisplay.

 -- Variable: redisplay-preemption-period
     If `redisplay-dont-pause' is `nil', this variable specifies how
     many seconds Emacs waits between checks for new input during
     redisplay; if input arrives during this interval, redisplay stops
     and the input is processed.  The default value is 0.1; if the
     value is `nil', Emacs does not check for input during redisplay.

     This variable has no effect when `redisplay-dont-pause' is
     non-`nil' (the default).

   Although `redisplay' tries immediately to redisplay, it does not
change how Emacs decides which parts of its frame(s) to redisplay.  By
contrast, the following function adds certain windows to the pending
redisplay work (as if their contents had completely changed), but does
not immediately try to perform redisplay.

 -- Function: force-window-update &optional object
     This function forces some or all windows to be updated the next
     time Emacs does a redisplay.  If OBJECT is a window, that window is
     to be updated.  If OBJECT is a buffer or buffer name, all windows
     displaying that buffer are to be updated.  If OBJECT is `nil' (or
     omitted), all windows are to be updated.

     This function does not do a redisplay immediately; Emacs does that
     as it waits for input, or when the function `redisplay' is called.


File: elisp,  Node: Truncation,  Next: The Echo Area,  Prev: Forcing Redisplay,  Up: Display

38.3 Truncation
===============

When a line of text extends beyond the right edge of a window, Emacs
can "continue" the line (make it "wrap" to the next screen line), or
"truncate" the line (limit it to one screen line).  The additional
screen lines used to display a long text line are called "continuation"
lines.  Continuation is not the same as filling; continuation happens
on the screen only, not in the buffer contents, and it breaks a line
precisely at the right margin, not at a word boundary.  *Note Filling::.

   On a graphical display, tiny arrow images in the window fringes
indicate truncated and continued lines (*note Fringes::).  On a text
terminal, a `$' in the rightmost column of the window indicates
truncation; a `\' on the rightmost column indicates a line that
"wraps".  (The display table can specify alternate characters to use
for this; *note Display Tables::).

 -- User Option: truncate-lines
     If this buffer-local variable is non-`nil', lines that extend
     beyond the right edge of the window are truncated; otherwise, they
     are continued.  As a special exception, the variable
     `truncate-partial-width-windows' takes precedence in
     "partial-width" windows (i.e. windows that do not occupy the
     entire frame width).

 -- User Option: truncate-partial-width-windows
     This variable controls line truncation in "partial-width" windows.
     A partial-width window is one that does not occupy the entire frame
     width (*note Splitting Windows::).  If the value is `nil', line
     truncation is determined by the variable `truncate-lines' (see
     above).  If the value is an integer N, lines are truncated if the
     partial-width window has fewer than N columns, regardless of the
     value of `truncate-lines'; if the partial-width window has N or
     more columns, line truncation is determined by `truncate-lines'.
     For any other non-`nil' value, lines are truncated in every
     partial-width window, regardless of the value of `truncate-lines'.

   When horizontal scrolling (*note Horizontal Scrolling::) is in use in
a window, that forces truncation.

 -- Variable: wrap-prefix
     If this buffer-local variable is non-`nil', it defines a "wrap
     prefix" which Emacs displays at the start of every continuation
     line.  (If lines are truncated, `wrap-prefix' is never used.)  Its
     value may be a string or an image (*note Other Display Specs::),
     or a stretch of whitespace such as specified by the `:width' or
     `:align-to' display properties (*note Specified Space::).  The
     value is interpreted in the same way as a `display' text property.
     *Note Display Property::.

     A wrap prefix may also be specified for regions of text, using the
     `wrap-prefix' text or overlay property.  This takes precedence
     over the `wrap-prefix' variable.  *Note Special Properties::.

 -- Variable: line-prefix
     If this buffer-local variable is non-`nil', it defines a "line
     prefix" which Emacs displays at the start of every
     non-continuation line.  Its value may be a string or an image
     (*note Other Display Specs::), or a stretch of whitespace such as
     specified by the `:width' or `:align-to' display properties (*note
     Specified Space::).  The value is interpreted in the same way as a
     `display' text property.  *Note Display Property::.

     A line prefix may also be specified for regions of text using the
     `line-prefix' text or overlay property.  This takes precedence
     over the `line-prefix' variable.  *Note Special Properties::.

   If your buffer contains _very_ long lines, and you use continuation
to display them, computing the continuation lines can make redisplay
slow.  The column computation and indentation functions also become
slow.  Then you might find it advisable to set `cache-long-line-scans'
to `t'.

 -- Variable: cache-long-line-scans
     If this variable is non-`nil', various indentation and motion
     functions, and Emacs redisplay, cache the results of scanning the
     buffer, and consult the cache to avoid rescanning regions of the
     buffer unless they are modified.

     Turning on the cache slows down processing of short lines somewhat.

     This variable is automatically buffer-local in every buffer.


File: elisp,  Node: The Echo Area,  Next: Warnings,  Prev: Truncation,  Up: Display

38.4 The Echo Area
==================

The "echo area" is used for displaying error messages (*note Errors::),
for messages made with the `message' primitive, and for echoing
keystrokes.  It is not the same as the minibuffer, despite the fact
that the minibuffer appears (when active) in the same place on the
screen as the echo area.  *Note The Minibuffer: (emacs)Minibuffer.

   Apart from the functions documented in this section, you can print
Lisp objects to the echo area by specifying `t' as the output stream.
*Note Output Streams::.

* Menu:

* Displaying Messages:: Explicitly displaying text in the echo area.
* Progress::            Informing user about progress of a long operation.
* Logging Messages::    Echo area messages are logged for the user.
* Echo Area Customization:: Controlling the echo area.


File: elisp,  Node: Displaying Messages,  Next: Progress,  Up: The Echo Area

38.4.1 Displaying Messages in the Echo Area
-------------------------------------------

This section describes the standard functions for displaying messages
in the echo area.

 -- Function: message format-string &rest arguments
     This function displays a message in the echo area.  FORMAT-STRING
     is a format string, and ARGUMENTS are the objects for its format
     specifications, like in the `format' function (*note Formatting
     Strings::).  The resulting formatted string is displayed in the
     echo area; if it contains `face' text properties, it is displayed
     with the specified faces (*note Faces::).  The string is also
     added to the `*Messages*' buffer, but without text properties
     (*note Logging Messages::).

     In batch mode, the message is printed to the standard error stream,
     followed by a newline.

     If FORMAT-STRING is `nil' or the empty string, `message' clears
     the echo area; if the echo area has been expanded automatically,
     this brings it back to its normal size.  If the minibuffer is
     active, this brings the minibuffer contents back onto the screen
     immediately.

          (message "Minibuffer depth is %d."
                   (minibuffer-depth))
           -| Minibuffer depth is 0.
          => "Minibuffer depth is 0."

          ---------- Echo Area ----------
          Minibuffer depth is 0.
          ---------- Echo Area ----------

     To automatically display a message in the echo area or in a
     pop-buffer, depending on its size, use `display-message-or-buffer'
     (see below).

 -- Macro: with-temp-message message &rest body
     This construct displays a message in the echo area temporarily,
     during the execution of BODY.  It displays MESSAGE, executes BODY,
     then returns the value of the last body form while restoring the
     previous echo area contents.

 -- Function: message-or-box format-string &rest arguments
     This function displays a message like `message', but may display it
     in a dialog box instead of the echo area.  If this function is
     called in a command that was invoked using the mouse--more
     precisely, if `last-nonmenu-event' (*note Command Loop Info::) is
     either `nil' or a list--then it uses a dialog box or pop-up menu to
     display the message.  Otherwise, it uses the echo area.  (This is
     the same criterion that `y-or-n-p' uses to make a similar
     decision; see *note Yes-or-No Queries::.)

     You can force use of the mouse or of the echo area by binding
     `last-nonmenu-event' to a suitable value around the call.

 -- Function: message-box format-string &rest arguments
     This function displays a message like `message', but uses a dialog
     box (or a pop-up menu) whenever that is possible.  If it is
     impossible to use a dialog box or pop-up menu, because the
     terminal does not support them, then `message-box' uses the echo
     area, like `message'.

 -- Function: display-message-or-buffer message &optional buffer-name
          not-this-window frame
     This function displays the message MESSAGE, which may be either a
     string or a buffer.  If it is shorter than the maximum height of
     the echo area, as defined by `max-mini-window-height', it is
     displayed in the echo area, using `message'.  Otherwise,
     `display-buffer' is used to show it in a pop-up buffer.

     Returns either the string shown in the echo area, or when a pop-up
     buffer is used, the window used to display it.

     If MESSAGE is a string, then the optional argument BUFFER-NAME is
     the name of the buffer used to display it when a pop-up buffer is
     used, defaulting to `*Message*'.  In the case where MESSAGE is a
     string and displayed in the echo area, it is not specified whether
     the contents are inserted into the buffer anyway.

     The optional arguments NOT-THIS-WINDOW and FRAME are as for
     `display-buffer', and only used if a buffer is displayed.

 -- Function: current-message
     This function returns the message currently being displayed in the
     echo area, or `nil' if there is none.


File: elisp,  Node: Progress,  Next: Logging Messages,  Prev: Displaying Messages,  Up: The Echo Area

38.4.2 Reporting Operation Progress
-----------------------------------

When an operation can take a while to finish, you should inform the
user about the progress it makes.  This way the user can estimate
remaining time and clearly see that Emacs is busy working, not hung.  A
convenient way to do this is to use a "progress reporter".

   Here is a working example that does nothing useful:

     (let ((progress-reporter
            (make-progress-reporter "Collecting mana for Emacs..."
                                    0  500)))
       (dotimes (k 500)
         (sit-for 0.01)
         (progress-reporter-update progress-reporter k))
       (progress-reporter-done progress-reporter))

 -- Function: make-progress-reporter message &optional min-value
          max-value current-value min-change min-time
     This function creates and returns a progress reporter object, which
     you will use as an argument for the other functions listed below.
     The idea is to precompute as much data as possible to make progress
     reporting very fast.

     When this progress reporter is subsequently used, it will display
     MESSAGE in the echo area, followed by progress percentage.
     MESSAGE is treated as a simple string.  If you need it to depend
     on a filename, for instance, use `format' before calling this
     function.

     The arguments MIN-VALUE and MAX-VALUE should be numbers standing
     for the starting and final states of the operation.  For instance,
     an operation that "scans" a buffer should set these to the results
     of `point-min' and `point-max' correspondingly.  MAX-VALUE should
     be greater than MIN-VALUE.

     Alternatively, you can set MIN-VALUE and MAX-VALUE to `nil'.  In
     that case, the progress reporter does not report process
     percentages; it instead displays a "spinner" that rotates a notch
     each time you update the progress reporter.

     If MIN-VALUE and MAX-VALUE are numbers, you can give the argument
     CURRENT-VALUE a numerical value specifying the initial progress;
     if omitted, this defaults to MIN-VALUE.

     The remaining arguments control the rate of echo area updates.  The
     progress reporter will wait for at least MIN-CHANGE more percents
     of the operation to be completed before printing next message; the
     default is one percent.  MIN-TIME specifies the minimum time in
     seconds to pass between successive prints; the default is 0.2
     seconds.  (On some operating systems, the progress reporter may
     handle fractions of seconds with varying precision).

     This function calls `progress-reporter-update', so the first
     message is printed immediately.

 -- Function: progress-reporter-update reporter &optional value
     This function does the main work of reporting progress of your
     operation.  It displays the message of REPORTER, followed by
     progress percentage determined by VALUE.  If percentage is zero,
     or close enough according to the MIN-CHANGE and MIN-TIME
     arguments, then it is omitted from the output.

     REPORTER must be the result of a call to `make-progress-reporter'.
     VALUE specifies the current state of your operation and must be
     between MIN-VALUE and MAX-VALUE (inclusive) as passed to
     `make-progress-reporter'.  For instance, if you scan a buffer,
     then VALUE should be the result of a call to `point'.

     This function respects MIN-CHANGE and MIN-TIME as passed to
     `make-progress-reporter' and so does not output new messages on
     every invocation.  It is thus very fast and normally you should not
     try to reduce the number of calls to it: resulting overhead will
     most likely negate your effort.

 -- Function: progress-reporter-force-update reporter &optional value
          new-message
     This function is similar to `progress-reporter-update' except that
     it prints a message in the echo area unconditionally.

     The first two arguments have the same meaning as for
     `progress-reporter-update'.  Optional NEW-MESSAGE allows you to
     change the message of the REPORTER.  Since this functions always
     updates the echo area, such a change will be immediately presented
     to the user.

 -- Function: progress-reporter-done reporter
     This function should be called when the operation is finished.  It
     prints the message of REPORTER followed by word "done" in the echo
     area.

     You should always call this function and not hope for
     `progress-reporter-update' to print "100%".  Firstly, it may never
     print it, there are many good reasons for this not to happen.
     Secondly, "done" is more explicit.

 -- Macro: dotimes-with-progress-reporter (var count [result]) message
          body...
     This is a convenience macro that works the same way as `dotimes'
     does, but also reports loop progress using the functions described
     above.  It allows you to save some typing.

     You can rewrite the example in the beginning of this node using
     this macro this way:

          (dotimes-with-progress-reporter
              (k 500)
              "Collecting some mana for Emacs..."
            (sit-for 0.01))


File: elisp,  Node: Logging Messages,  Next: Echo Area Customization,  Prev: Progress,  Up: The Echo Area

38.4.3 Logging Messages in `*Messages*'
---------------------------------------

Almost all the messages displayed in the echo area are also recorded in
the `*Messages*' buffer so that the user can refer back to them.  This
includes all the messages that are output with `message'.

 -- User Option: message-log-max
     This variable specifies how many lines to keep in the `*Messages*'
     buffer.  The value `t' means there is no limit on how many lines to
     keep.  The value `nil' disables message logging entirely.  Here's
     how to display a message and prevent it from being logged:

          (let (message-log-max)
            (message ...))

   To make `*Messages*' more convenient for the user, the logging
facility combines successive identical messages.  It also combines
successive related messages for the sake of two cases: question
followed by answer, and a series of progress messages.

   A "question followed by an answer" means two messages like the ones
produced by `y-or-n-p': the first is `QUESTION', and the second is
`QUESTION...ANSWER'.  The first message conveys no additional
information beyond what's in the second, so logging the second message
discards the first from the log.

   A "series of progress messages" means successive messages like those
produced by `make-progress-reporter'.  They have the form
`BASE...HOW-FAR', where BASE is the same each time, while HOW-FAR
varies.  Logging each message in the series discards the previous one,
provided they are consecutive.

   The functions `make-progress-reporter' and `y-or-n-p' don't have to
do anything special to activate the message log combination feature.
It operates whenever two consecutive messages are logged that share a
common prefix ending in `...'.


File: elisp,  Node: Echo Area Customization,  Prev: Logging Messages,  Up: The Echo Area

38.4.4 Echo Area Customization
------------------------------

These variables control details of how the echo area works.

 -- Variable: cursor-in-echo-area
     This variable controls where the cursor appears when a message is
     displayed in the echo area.  If it is non-`nil', then the cursor
     appears at the end of the message.  Otherwise, the cursor appears
     at point--not in the echo area at all.

     The value is normally `nil'; Lisp programs bind it to `t' for
     brief periods of time.

 -- Variable: echo-area-clear-hook
     This normal hook is run whenever the echo area is cleared--either
     by `(message nil)' or for any other reason.

 -- User Option: echo-keystrokes
     This variable determines how much time should elapse before command
     characters echo.  Its value must be an integer or floating point
     number, which specifies the number of seconds to wait before
     echoing.  If the user types a prefix key (such as `C-x') and then
     delays this many seconds before continuing, the prefix key is
     echoed in the echo area.  (Once echoing begins in a key sequence,
     all subsequent characters in the same key sequence are echoed
     immediately.)

     If the value is zero, then command input is not echoed.

 -- Variable: message-truncate-lines
     Normally, displaying a long message resizes the echo area to
     display the entire message.  But if the variable
     `message-truncate-lines' is non-`nil', the echo area does not
     resize, and the message is truncated to fit it.

   The variable `max-mini-window-height', which specifies the maximum
height for resizing minibuffer windows, also applies to the echo area
(which is really a special use of the minibuffer window; *note
Minibuffer Misc::).


File: elisp,  Node: Warnings,  Next: Invisible Text,  Prev: The Echo Area,  Up: Display

38.5 Reporting Warnings
=======================

"Warnings" are a facility for a program to inform the user of a
possible problem, but continue running.

* Menu:

* Warning Basics::      Warnings concepts and functions to report them.
* Warning Variables::   Variables programs bind to customize their warnings.
* Warning Options::     Variables users set to control display of warnings.
* Delayed Warnings::    Deferring a warning until the end of a command.


File: elisp,  Node: Warning Basics,  Next: Warning Variables,  Up: Warnings

38.5.1 Warning Basics
---------------------

Every warning has a textual message, which explains the problem for the
user, and a "severity level" which is a symbol.  Here are the possible
severity levels, in order of decreasing severity, and their meanings:

`:emergency'
     A problem that will seriously impair Emacs operation soon if you
     do not attend to it promptly.

`:error'
     A report of data or circumstances that are inherently wrong.

`:warning'
     A report of data or circumstances that are not inherently wrong,
     but raise suspicion of a possible problem.

`:debug'
     A report of information that may be useful if you are debugging.

   When your program encounters invalid input data, it can either
signal a Lisp error by calling `error' or `signal' or report a warning
with severity `:error'.  Signaling a Lisp error is the easiest thing to
do, but it means the program cannot continue processing.  If you want
to take the trouble to implement a way to continue processing despite
the bad data, then reporting a warning of severity `:error' is the
right way to inform the user of the problem.  For instance, the Emacs
Lisp byte compiler can report an error that way and continue compiling
other functions.  (If the program signals a Lisp error and then handles
it with `condition-case', the user won't see the error message; it could
show the message to the user by reporting it as a warning.)

   Each warning has a "warning type" to classify it.  The type is a
list of symbols.  The first symbol should be the custom group that you
use for the program's user options.  For example, byte compiler
warnings use the warning type `(bytecomp)'.  You can also subcategorize
the warnings, if you wish, by using more symbols in the list.

 -- Function: display-warning type message &optional level buffer-name
     This function reports a warning, using MESSAGE as the message and
     TYPE as the warning type.  LEVEL should be the severity level,
     with `:warning' being the default.

     BUFFER-NAME, if non-`nil', specifies the name of the buffer for
     logging the warning.  By default, it is `*Warnings*'.

 -- Function: lwarn type level message &rest args
     This function reports a warning using the value of `(format
     MESSAGE ARGS...)' as the message.  In other respects it is
     equivalent to `display-warning'.

 -- Function: warn message &rest args
     This function reports a warning using the value of `(format
     MESSAGE ARGS...)' as the message, `(emacs)' as the type, and
     `:warning' as the severity level.  It exists for compatibility
     only; we recommend not using it, because you should specify a
     specific warning type.


File: elisp,  Node: Warning Variables,  Next: Warning Options,  Prev: Warning Basics,  Up: Warnings

38.5.2 Warning Variables
------------------------

Programs can customize how their warnings appear by binding the
variables described in this section.

 -- Variable: warning-levels
     This list defines the meaning and severity order of the warning
     severity levels.  Each element defines one severity level, and
     they are arranged in order of decreasing severity.

     Each element has the form `(LEVEL STRING FUNCTION)', where LEVEL
     is the severity level it defines.  STRING specifies the textual
     description of this level.  STRING should use `%s' to specify
     where to put the warning type information, or it can omit the `%s'
     so as not to include that information.

     The optional FUNCTION, if non-`nil', is a function to call with no
     arguments, to get the user's attention.

     Normally you should not change the value of this variable.

 -- Variable: warning-prefix-function
     If non-`nil', the value is a function to generate prefix text for
     warnings.  Programs can bind the variable to a suitable function.
     `display-warning' calls this function with the warnings buffer
     current, and the function can insert text in it.  That text becomes
     the beginning of the warning message.

     The function is called with two arguments, the severity level and
     its entry in `warning-levels'.  It should return a list to use as
     the entry (this value need not be an actual member of
     `warning-levels').  By constructing this value, the function can
     change the severity of the warning, or specify different handling
     for a given severity level.

     If the variable's value is `nil' then there is no function to call.

 -- Variable: warning-series
     Programs can bind this variable to `t' to say that the next
     warning should begin a series.  When several warnings form a
     series, that means to leave point on the first warning of the
     series, rather than keep moving it for each warning so that it
     appears on the last one.  The series ends when the local binding
     is unbound and `warning-series' becomes `nil' again.

     The value can also be a symbol with a function definition.  That is
     equivalent to `t', except that the next warning will also call the
     function with no arguments with the warnings buffer current.  The
     function can insert text which will serve as a header for the
     series of warnings.

     Once a series has begun, the value is a marker which points to the
     buffer position in the warnings buffer of the start of the series.

     The variable's normal value is `nil', which means to handle each
     warning separately.

 -- Variable: warning-fill-prefix
     When this variable is non-`nil', it specifies a fill prefix to use
     for filling each warning's text.

 -- Variable: warning-type-format
     This variable specifies the format for displaying the warning type
     in the warning message.  The result of formatting the type this way
     gets included in the message under the control of the string in the
     entry in `warning-levels'.  The default value is `" (%s)"'.  If
     you bind it to `""' then the warning type won't appear at all.


File: elisp,  Node: Warning Options,  Next: Delayed Warnings,  Prev: Warning Variables,  Up: Warnings

38.5.3 Warning Options
----------------------

These variables are used by users to control what happens when a Lisp
program reports a warning.

 -- User Option: warning-minimum-level
     This user option specifies the minimum severity level that should
     be shown immediately to the user.  The default is `:warning', which
     means to immediately display all warnings except `:debug' warnings.

 -- User Option: warning-minimum-log-level
     This user option specifies the minimum severity level that should
     be logged in the warnings buffer.  The default is `:warning', which
     means to log all warnings except `:debug' warnings.

 -- User Option: warning-suppress-types
     This list specifies which warning types should not be displayed
     immediately for the user.  Each element of the list should be a
     list of symbols.  If its elements match the first elements in a
     warning type, then that warning is not displayed immediately.

 -- User Option: warning-suppress-log-types
     This list specifies which warning types should not be logged in the
     warnings buffer.  Each element of the list should be a list of
     symbols.  If it matches the first few elements in a warning type,
     then that warning is not logged.


File: elisp,  Node: Delayed Warnings,  Prev: Warning Options,  Up: Warnings

38.5.4 Delayed Warnings
-----------------------

Sometimes, you may wish to avoid showing a warning while a command is
running, and only show it only after the end of the command.  You can
use the variable `delayed-warnings-list' for this.

 -- Variable: delayed-warnings-list
     The value of this variable is a list of warnings to be displayed
     after the current command has finished.  Each element must be a
     list

          (TYPE MESSAGE [LEVEL [BUFFER-NAME]])

     with the same form, and the same meanings, as the argument list of
     `display-warning' (*note Warning Basics::).  Immediately after
     running `post-command-hook' (*note Command Overview::), the Emacs
     command loop displays all the warnings specified by this variable,
     then resets it to `nil'.

   Programs which need to further customize the delayed warnings
mechanism can change the variable `delayed-warnings-hook':

 -- Variable: delayed-warnings-hook
     This is a normal hook which is run by the Emacs command loop, after
     `post-command-hook', in order to to process and display delayed
     warnings.

     Its default value is a list of two functions:

          (collapse-delayed-warnings display-delayed-warnings)

     The function `collapse-delayed-warnings' removes repeated entries
     from `delayed-warnings-list'.  The function
     `display-delayed-warnings' calls `display-warning' on each of the
     entries in `delayed-warnings-list', in turn, and then sets
     `delayed-warnings-list' to `nil'.


File: elisp,  Node: Invisible Text,  Next: Selective Display,  Prev: Warnings,  Up: Display

38.6 Invisible Text
===================

You can make characters "invisible", so that they do not appear on the
screen, with the `invisible' property.  This can be either a text
property (*note Text Properties::) or an overlay property (*note
Overlays::).  Cursor motion also partly ignores these characters; if
the command loop finds that point is inside a range of invisible text
after a command, it relocates point to the other side of the text.

   In the simplest case, any non-`nil' `invisible' property makes a
character invisible.  This is the default case--if you don't alter the
default value of `buffer-invisibility-spec', this is how the
`invisible' property works.  You should normally use `t' as the value
of the `invisible' property if you don't plan to set
`buffer-invisibility-spec' yourself.

   More generally, you can use the variable `buffer-invisibility-spec'
to control which values of the `invisible' property make text
invisible.  This permits you to classify the text into different subsets
in advance, by giving them different `invisible' values, and
subsequently make various subsets visible or invisible by changing the
value of `buffer-invisibility-spec'.

   Controlling visibility with `buffer-invisibility-spec' is especially
useful in a program to display the list of entries in a database.  It
permits the implementation of convenient filtering commands to view
just a part of the entries in the database.  Setting this variable is
very fast, much faster than scanning all the text in the buffer looking
for properties to change.

 -- Variable: buffer-invisibility-spec
     This variable specifies which kinds of `invisible' properties
     actually make a character invisible.  Setting this variable makes
     it buffer-local.

    `t'
          A character is invisible if its `invisible' property is
          non-`nil'.  This is the default.

    a list
          Each element of the list specifies a criterion for
          invisibility; if a character's `invisible' property fits any
          one of these criteria, the character is invisible.  The list
          can have two kinds of elements:

         `ATOM'
               A character is invisible if its `invisible' property
               value is ATOM or if it is a list with ATOM as a member;
               comparison is done with `eq'.

         `(ATOM . t)'
               A character is invisible if its `invisible' property
               value is ATOM or if it is a list with ATOM as a member;
               comparison is done with `eq'.  Moreover, a sequence of
               such characters displays as an ellipsis.

   Two functions are specifically provided for adding elements to
`buffer-invisibility-spec' and removing elements from it.

 -- Function: add-to-invisibility-spec element
     This function adds the element ELEMENT to
     `buffer-invisibility-spec'.  If `buffer-invisibility-spec' was
     `t', it changes to a list, `(t)', so that text whose `invisible'
     property is `t' remains invisible.

 -- Function: remove-from-invisibility-spec element
     This removes the element ELEMENT from `buffer-invisibility-spec'.
     This does nothing if ELEMENT is not in the list.

   A convention for use of `buffer-invisibility-spec' is that a major
mode should use the mode's own name as an element of
`buffer-invisibility-spec' and as the value of the `invisible' property:

     ;; If you want to display an ellipsis:
     (add-to-invisibility-spec '(my-symbol . t))
     ;; If you don't want ellipsis:
     (add-to-invisibility-spec 'my-symbol)

     (overlay-put (make-overlay beginning end)
                  'invisible 'my-symbol)

     ;; When done with the invisibility:
     (remove-from-invisibility-spec '(my-symbol . t))
     ;; Or respectively:
     (remove-from-invisibility-spec 'my-symbol)

   You can check for invisibility using the following function:

 -- Function: invisible-p pos-or-prop
     If POS-OR-PROP is a marker or number, this function returns a
     non-`nil' value if the text at that position is invisible.

     If POS-OR-PROP is any other kind of Lisp object, that is taken to
     mean a possible value of the `invisible' text or overlay property.
     In that case, this function returns a non-`nil' value if that
     value would cause text to become invisible, based on the current
     value of `buffer-invisibility-spec'.

   Ordinarily, functions that operate on text or move point do not care
whether the text is invisible.  The user-level line motion commands
ignore invisible newlines if `line-move-ignore-invisible' is non-`nil'
(the default), but only because they are explicitly programmed to do so.

   However, if a command ends with point inside or at the boundary of
invisible text, the main editing loop relocates point to one of the two
ends of the invisible text.  Emacs chooses the direction of relocation
so that it is the same as the overall movement direction of the
command; if in doubt, it prefers a position where an inserted char
would not inherit the `invisible' property.  Additionally, if the text
is not replaced by an ellipsis and the command only moved within the
invisible text, then point is moved one extra character so as to try
and reflect the command's movement by a visible movement of the cursor.

   Thus, if the command moved point back to an invisible range (with
the usual stickiness), Emacs moves point back to the beginning of that
range.  If the command moved point forward into an invisible range,
Emacs moves point forward to the first visible character that follows
the invisible text and then forward one more character.

   Incremental search can make invisible overlays visible temporarily
and/or permanently when a match includes invisible text.  To enable
this, the overlay should have a non-`nil' `isearch-open-invisible'
property.  The property value should be a function to be called with
the overlay as an argument.  This function should make the overlay
visible permanently; it is used when the match overlaps the overlay on
exit from the search.

   During the search, such overlays are made temporarily visible by
temporarily modifying their invisible and intangible properties.  If you
want this to be done differently for a certain overlay, give it an
`isearch-open-invisible-temporary' property which is a function.  The
function is called with two arguments: the first is the overlay, and
the second is `nil' to make the overlay visible, or `t' to make it
invisible again.


File: elisp,  Node: Selective Display,  Next: Temporary Displays,  Prev: Invisible Text,  Up: Display

38.7 Selective Display
======================

"Selective display" refers to a pair of related features for hiding
certain lines on the screen.

   The first variant, explicit selective display, is designed for use
in a Lisp program: it controls which lines are hidden by altering the
text.  This kind of hiding in some ways resembles the effect of the
`invisible' property (*note Invisible Text::), but the two features are
different and do not work the same way.

   In the second variant, the choice of lines to hide is made
automatically based on indentation.  This variant is designed to be a
user-level feature.

   The way you control explicit selective display is by replacing a
newline (control-j) with a carriage return (control-m).  The text that
was formerly a line following that newline is now hidden.  Strictly
speaking, it is temporarily no longer a line at all, since only
newlines can separate lines; it is now part of the previous line.

   Selective display does not directly affect editing commands.  For
example, `C-f' (`forward-char') moves point unhesitatingly into hidden
text.  However, the replacement of newline characters with carriage
return characters affects some editing commands.  For example,
`next-line' skips hidden lines, since it searches only for newlines.
Modes that use selective display can also define commands that take
account of the newlines, or that control which parts of the text are
hidden.

   When you write a selectively displayed buffer into a file, all the
control-m's are output as newlines.  This means that when you next read
in the file, it looks OK, with nothing hidden.  The selective display
effect is seen only within Emacs.

 -- Variable: selective-display
     This buffer-local variable enables selective display.  This means
     that lines, or portions of lines, may be made hidden.

        * If the value of `selective-display' is `t', then the character
          control-m marks the start of hidden text; the control-m, and
          the rest of the line following it, are not displayed.  This
          is explicit selective display.

        * If the value of `selective-display' is a positive integer,
          then lines that start with more than that many columns of
          indentation are not displayed.

     When some portion of a buffer is hidden, the vertical movement
     commands operate as if that portion did not exist, allowing a
     single `next-line' command to skip any number of hidden lines.
     However, character movement commands (such as `forward-char') do
     not skip the hidden portion, and it is possible (if tricky) to
     insert or delete text in an hidden portion.

     In the examples below, we show the _display appearance_ of the
     buffer `foo', which changes with the value of `selective-display'.
     The _contents_ of the buffer do not change.

          (setq selective-display nil)
               => nil

          ---------- Buffer: foo ----------
          1 on this column
           2on this column
            3n this column
            3n this column
           2on this column
          1 on this column
          ---------- Buffer: foo ----------

          (setq selective-display 2)
               => 2

          ---------- Buffer: foo ----------
          1 on this column
           2on this column
           2on this column
          1 on this column
          ---------- Buffer: foo ----------

 -- User Option: selective-display-ellipses
     If this buffer-local variable is non-`nil', then Emacs displays
     `...' at the end of a line that is followed by hidden text.  This
     example is a continuation of the previous one.

          (setq selective-display-ellipses t)
               => t

          ---------- Buffer: foo ----------
          1 on this column
           2on this column ...
           2on this column
          1 on this column
          ---------- Buffer: foo ----------

     You can use a display table to substitute other text for the
     ellipsis (`...').  *Note Display Tables::.


File: elisp,  Node: Temporary Displays,  Next: Overlays,  Prev: Selective Display,  Up: Display

38.8 Temporary Displays
=======================

Temporary displays are used by Lisp programs to put output into a
buffer and then present it to the user for perusal rather than for
editing.  Many help commands use this feature.

 -- Macro: with-output-to-temp-buffer buffer-name forms...
     This function executes FORMS while arranging to insert any output
     they print into the buffer named BUFFER-NAME, which is first
     created if necessary, and put into Help mode.  Finally, the buffer
     is displayed in some window, but not selected.

     If the FORMS do not change the major mode in the output buffer, so
     that it is still Help mode at the end of their execution, then
     `with-output-to-temp-buffer' makes this buffer read-only at the
     end, and also scans it for function and variable names to make them
     into clickable cross-references.  *Note Tips for Documentation
     Strings: Docstring hyperlinks, in particular the item on
     hyperlinks in documentation strings, for more details.

     The string BUFFER-NAME specifies the temporary buffer, which need
     not already exist.  The argument must be a string, not a buffer.
     The buffer is erased initially (with no questions asked), and it is
     marked as unmodified after `with-output-to-temp-buffer' exits.

     `with-output-to-temp-buffer' binds `standard-output' to the
     temporary buffer, then it evaluates the forms in FORMS.  Output
     using the Lisp output functions within FORMS goes by default to
     that buffer (but screen display and messages in the echo area,
     although they are "output" in the general sense of the word, are
     not affected).  *Note Output Functions::.

     Several hooks are available for customizing the behavior of this
     construct; they are listed below.

     The value of the last form in FORMS is returned.

          ---------- Buffer: foo ----------
           This is the contents of foo.
          ---------- Buffer: foo ----------

          (with-output-to-temp-buffer "foo"
              (print 20)
              (print standard-output))
          => #<buffer foo>

          ---------- Buffer: foo ----------
          20

          #<buffer foo>

          ---------- Buffer: foo ----------

 -- User Option: temp-buffer-show-function
     If this variable is non-`nil', `with-output-to-temp-buffer' calls
     it as a function to do the job of displaying a help buffer.  The
     function gets one argument, which is the buffer it should display.

     It is a good idea for this function to run `temp-buffer-show-hook'
     just as `with-output-to-temp-buffer' normally would, inside of
     `save-selected-window' and with the chosen window and buffer
     selected.

 -- Variable: temp-buffer-setup-hook
     This normal hook is run by `with-output-to-temp-buffer' before
     evaluating BODY.  When the hook runs, the temporary buffer is
     current.  This hook is normally set up with a function to put the
     buffer in Help mode.

 -- Variable: temp-buffer-show-hook
     This normal hook is run by `with-output-to-temp-buffer' after
     displaying the temporary buffer.  When the hook runs, the
     temporary buffer is current, and the window it was displayed in is
     selected.

 -- Function: momentary-string-display string position &optional char
          message
     This function momentarily displays STRING in the current buffer at
     POSITION.  It has no effect on the undo list or on the buffer's
     modification status.

     The momentary display remains until the next input event.  If the
     next input event is CHAR, `momentary-string-display' ignores it
     and returns.  Otherwise, that event remains buffered for
     subsequent use as input.  Thus, typing CHAR will simply remove the
     string from the display, while typing (say) `C-f' will remove the
     string from the display and later (presumably) move point forward.
     The argument CHAR is a space by default.

     The return value of `momentary-string-display' is not meaningful.

     If the string STRING does not contain control characters, you can
     do the same job in a more general way by creating (and then
     subsequently deleting) an overlay with a `before-string' property.
     *Note Overlay Properties::.

     If MESSAGE is non-`nil', it is displayed in the echo area while
     STRING is displayed in the buffer.  If it is `nil', a default
     message says to type CHAR to continue.

     In this example, point is initially located at the beginning of the
     second line:

          ---------- Buffer: foo ----------
          This is the contents of foo.
          -!-Second line.
          ---------- Buffer: foo ----------

          (momentary-string-display
            "**** Important Message! ****"
            (point) ?\r
            "Type RET when done reading")
          => t

          ---------- Buffer: foo ----------
          This is the contents of foo.
          **** Important Message! ****Second line.
          ---------- Buffer: foo ----------

          ---------- Echo Area ----------
          Type RET when done reading
          ---------- Echo Area ----------


File: elisp,  Node: Overlays,  Next: Width,  Prev: Temporary Displays,  Up: Display

38.9 Overlays
=============

You can use "overlays" to alter the appearance of a buffer's text on
the screen, for the sake of presentation features.  An overlay is an
object that belongs to a particular buffer, and has a specified
beginning and end.  It also has properties that you can examine and set;
these affect the display of the text within the overlay.

   The visual effect of an overlay is the same as of the corresponding
text property (*note Text Properties::).  However, due to a different
implementation, overlays generally don't scale well (many operations
take a time that is proportional to the number of overlays in the
buffer).  If you need to affect the visual appearance of many portions
in the buffer, we recommend using text properties.

   An overlay uses markers to record its beginning and end; thus,
editing the text of the buffer adjusts the beginning and end of each
overlay so that it stays with the text.  When you create the overlay,
you can specify whether text inserted at the beginning should be inside
the overlay or outside, and likewise for the end of the overlay.

* Menu:

* Managing Overlays::   Creating and moving overlays.
* Overlay Properties::  How to read and set properties.
                          What properties do to the screen display.
* Finding Overlays::    Searching for overlays.


File: elisp,  Node: Managing Overlays,  Next: Overlay Properties,  Up: Overlays

38.9.1 Managing Overlays
------------------------

This section describes the functions to create, delete and move
overlays, and to examine their contents.  Overlay changes are not
recorded in the buffer's undo list, since the overlays are not part of
the buffer's contents.

 -- Function: overlayp object
     This function returns `t' if OBJECT is an overlay.

 -- Function: make-overlay start end &optional buffer front-advance
          rear-advance
     This function creates and returns an overlay that belongs to
     BUFFER and ranges from START to END.  Both START and END must
     specify buffer positions; they may be integers or markers.  If
     BUFFER is omitted, the overlay is created in the current buffer.

     The arguments FRONT-ADVANCE and REAR-ADVANCE specify the marker
     insertion type for the start of the overlay and for the end of the
     overlay, respectively.  *Note Marker Insertion Types::.  If they
     are both `nil', the default, then the overlay extends to include
     any text inserted at the beginning, but not text inserted at the
     end.  If FRONT-ADVANCE is non-`nil', text inserted at the
     beginning of the overlay is excluded from the overlay.  If
     REAR-ADVANCE is non-`nil', text inserted at the end of the overlay
     is included in the overlay.

 -- Function: overlay-start overlay
     This function returns the position at which OVERLAY starts, as an
     integer.

 -- Function: overlay-end overlay
     This function returns the position at which OVERLAY ends, as an
     integer.

 -- Function: overlay-buffer overlay
     This function returns the buffer that OVERLAY belongs to.  It
     returns `nil' if OVERLAY has been deleted.

 -- Function: delete-overlay overlay
     This function deletes OVERLAY.  The overlay continues to exist as
     a Lisp object, and its property list is unchanged, but it ceases
     to be attached to the buffer it belonged to, and ceases to have
     any effect on display.

     A deleted overlay is not permanently disconnected.  You can give
     it a position in a buffer again by calling `move-overlay'.

 -- Function: move-overlay overlay start end &optional buffer
     This function moves OVERLAY to BUFFER, and places its bounds at
     START and END.  Both arguments START and END must specify buffer
     positions; they may be integers or markers.

     If BUFFER is omitted, OVERLAY stays in the same buffer it was
     already associated with; if OVERLAY was deleted, it goes into the
     current buffer.

     The return value is OVERLAY.

     This is the only valid way to change the endpoints of an overlay.
     Do not try modifying the markers in the overlay by hand, as that
     fails to update other vital data structures and can cause some
     overlays to be "lost".

 -- Function: remove-overlays &optional start end name value
     This function removes all the overlays between START and END whose
     property NAME has the value VALUE.  It can move the endpoints of
     the overlays in the region, or split them.

     If NAME is omitted or `nil', it means to delete all overlays in
     the specified region.  If START and/or END are omitted or `nil',
     that means the beginning and end of the buffer respectively.
     Therefore, `(remove-overlays)' removes all the overlays in the
     current buffer.

 -- Function: copy-overlay overlay
     This function returns a copy of OVERLAY.  The copy has the same
     endpoints and properties as OVERLAY.  However, the marker
     insertion type for the start of the overlay and for the end of the
     overlay are set to their default values (*note Marker Insertion
     Types::).

   Here are some examples:

     ;; Create an overlay.
     (setq foo (make-overlay 1 10))
          => #<overlay from 1 to 10 in display.texi>
     (overlay-start foo)
          => 1
     (overlay-end foo)
          => 10
     (overlay-buffer foo)
          => #<buffer display.texi>
     ;; Give it a property we can check later.
     (overlay-put foo 'happy t)
          => t
     ;; Verify the property is present.
     (overlay-get foo 'happy)
          => t
     ;; Move the overlay.
     (move-overlay foo 5 20)
          => #<overlay from 5 to 20 in display.texi>
     (overlay-start foo)
          => 5
     (overlay-end foo)
          => 20
     ;; Delete the overlay.
     (delete-overlay foo)
          => nil
     ;; Verify it is deleted.
     foo
          => #<overlay in no buffer>
     ;; A deleted overlay has no position.
     (overlay-start foo)
          => nil
     (overlay-end foo)
          => nil
     (overlay-buffer foo)
          => nil
     ;; Undelete the overlay.
     (move-overlay foo 1 20)
          => #<overlay from 1 to 20 in display.texi>
     ;; Verify the results.
     (overlay-start foo)
          => 1
     (overlay-end foo)
          => 20
     (overlay-buffer foo)
          => #<buffer display.texi>
     ;; Moving and deleting the overlay does not change its properties.
     (overlay-get foo 'happy)
          => t

   Emacs stores the overlays of each buffer in two lists, divided
around an arbitrary "center position".  One list extends backwards
through the buffer from that center position, and the other extends
forwards from that center position.  The center position can be anywhere
in the buffer.

 -- Function: overlay-recenter pos
     This function recenters the overlays of the current buffer around
     position POS.  That makes overlay lookup faster for positions near
     POS, but slower for positions far away from POS.

   A loop that scans the buffer forwards, creating overlays, can run
faster if you do `(overlay-recenter (point-max))' first.


File: elisp,  Node: Overlay Properties,  Next: Finding Overlays,  Prev: Managing Overlays,  Up: Overlays

38.9.2 Overlay Properties
-------------------------

Overlay properties are like text properties in that the properties that
alter how a character is displayed can come from either source.  But in
most respects they are different.  *Note Text Properties::, for
comparison.

   Text properties are considered a part of the text; overlays and
their properties are specifically considered not to be part of the
text.  Thus, copying text between various buffers and strings preserves
text properties, but does not try to preserve overlays.  Changing a
buffer's text properties marks the buffer as modified, while moving an
overlay or changing its properties does not.  Unlike text property
changes, overlay property changes are not recorded in the buffer's undo
list.

   Since more than one overlay can specify a property value for the
same character, Emacs lets you specify a priority value of each
overlay.  You should not make assumptions about which overlay will
prevail when there is a conflict and they have the same priority.

   These functions read and set the properties of an overlay:

 -- Function: overlay-get overlay prop
     This function returns the value of property PROP recorded in
     OVERLAY, if any.  If OVERLAY does not record any value for that
     property, but it does have a `category' property which is a
     symbol, that symbol's PROP property is used.  Otherwise, the value
     is `nil'.

 -- Function: overlay-put overlay prop value
     This function sets the value of property PROP recorded in OVERLAY
     to VALUE.  It returns VALUE.

 -- Function: overlay-properties overlay
     This returns a copy of the property list of OVERLAY.

   See also the function `get-char-property' which checks both overlay
properties and text properties for a given character.  *Note Examining
Properties::.

   Many overlay properties have special meanings; here is a table of
them:

`priority'
     This property's value (which should be a non-negative integer
     number) determines the priority of the overlay.  No priority, or
     `nil', means zero.

     The priority matters when two or more overlays cover the same
     character and both specify the same property; the one whose
     `priority' value is larger overrides the other.  For the `face'
     property, the higher priority overlay's value does not completely
     override the other value; instead, its face attributes override
     the face attributes of the lower priority `face' property.

     Currently, all overlays take priority over text properties.  Please
     avoid using negative priority values, as we have not yet decided
     just what they should mean.

`window'
     If the `window' property is non-`nil', then the overlay applies
     only on that window.

`category'
     If an overlay has a `category' property, we call it the "category"
     of the overlay.  It should be a symbol.  The properties of the
     symbol serve as defaults for the properties of the overlay.

`face'
     This property controls the way text is displayed--for example,
     which font and which colors.  *Note Faces::, for more information.

     In the simplest case, the value is a face name.  It can also be a
     list; then each element can be any of these possibilities:

        * A face name (a symbol or string).

        * A property list of face attributes.  This has the form
          (KEYWORD VALUE ...), where each KEYWORD is a face attribute
          name and VALUE is a meaningful value for that attribute.  With
          this feature, you do not need to create a face each time you
          want to specify a particular attribute for certain text.
          *Note Face Attributes::.

        * A cons cell, of the form `(foreground-color . COLOR-NAME)' or
          `(background-color . COLOR-NAME)'.  These elements specify
          just the foreground color or just the background color.

          `(foreground-color . COLOR-NAME)' has the same effect as
          `(:foreground COLOR-NAME)'; likewise for the background.

`mouse-face'
     This property is used instead of `face' when the mouse is within
     the range of the overlay.  However, Emacs ignores all face
     attributes from this property that alter the text size (e.g.
     `:height', `:weight', and `:slant').  Those attributes are always
     the same as in the unhighlighted text.

`display'
     This property activates various features that change the way text
     is displayed.  For example, it can make text appear taller or
     shorter, higher or lower, wider or narrower, or replaced with an
     image.  *Note Display Property::.

`help-echo'
     If an overlay has a `help-echo' property, then when you move the
     mouse onto the text in the overlay, Emacs displays a help string
     in the echo area, or in the tooltip window.  For details see *note
     Text help-echo::.

`modification-hooks'
     This property's value is a list of functions to be called if any
     character within the overlay is changed or if text is inserted
     strictly within the overlay.

     The hook functions are called both before and after each change.
     If the functions save the information they receive, and compare
     notes between calls, they can determine exactly what change has
     been made in the buffer text.

     When called before a change, each function receives four
     arguments: the overlay, `nil', and the beginning and end of the
     text range to be modified.

     When called after a change, each function receives five arguments:
     the overlay, `t', the beginning and end of the text range just
     modified, and the length of the pre-change text replaced by that
     range.  (For an insertion, the pre-change length is zero; for a
     deletion, that length is the number of characters deleted, and the
     post-change beginning and end are equal.)

     If these functions modify the buffer, they should bind
     `inhibit-modification-hooks' to `t' around doing so, to avoid
     confusing the internal mechanism that calls these hooks.

     Text properties also support the `modification-hooks' property,
     but the details are somewhat different (*note Special
     Properties::).

`insert-in-front-hooks'
     This property's value is a list of functions to be called before
     and after inserting text right at the beginning of the overlay.
     The calling conventions are the same as for the
     `modification-hooks' functions.

`insert-behind-hooks'
     This property's value is a list of functions to be called before
     and after inserting text right at the end of the overlay.  The
     calling conventions are the same as for the `modification-hooks'
     functions.

`invisible'
     The `invisible' property can make the text in the overlay
     invisible, which means that it does not appear on the screen.
     *Note Invisible Text::, for details.

`intangible'
     The `intangible' property on an overlay works just like the
     `intangible' text property.  *Note Special Properties::, for
     details.

`isearch-open-invisible'
     This property tells incremental search how to make an invisible
     overlay visible, permanently, if the final match overlaps it.
     *Note Invisible Text::.

`isearch-open-invisible-temporary'
     This property tells incremental search how to make an invisible
     overlay visible, temporarily, during the search.  *Note Invisible
     Text::.

`before-string'
     This property's value is a string to add to the display at the
     beginning of the overlay.  The string does not appear in the
     buffer in any sense--only on the screen.

`after-string'
     This property's value is a string to add to the display at the end
     of the overlay.  The string does not appear in the buffer in any
     sense--only on the screen.

`line-prefix'
     This property specifies a display spec to prepend to each
     non-continuation line at display-time.  *Note Truncation::.

`wrap-prefix'
     This property specifies a display spec to prepend to each
     continuation line at display-time.  *Note Truncation::.

`evaporate'
     If this property is non-`nil', the overlay is deleted automatically
     if it becomes empty (i.e., if its length becomes zero).  If you
     give an empty overlay a non-`nil' `evaporate' property, that
     deletes it immediately.

`local-map'
     If this property is non-`nil', it specifies a keymap for a portion
     of the text.  The property's value replaces the buffer's local
     map, when the character after point is within the overlay.  *Note
     Active Keymaps::.

`keymap'
     The `keymap' property is similar to `local-map' but overrides the
     buffer's local map (and the map specified by the `local-map'
     property) rather than replacing it.

   The `local-map' and `keymap' properties do not affect a string
displayed by the `before-string', `after-string', or `display'
properties.  This is only relevant for mouse clicks and other mouse
events that fall on the string, since point is never on the string.  To
bind special mouse events for the string, assign it a `local-map' or
`keymap' text property.  *Note Special Properties::.


File: elisp,  Node: Finding Overlays,  Prev: Overlay Properties,  Up: Overlays

38.9.3 Searching for Overlays
-----------------------------

 -- Function: overlays-at pos
     This function returns a list of all the overlays that cover the
     character at position POS in the current buffer.  The list is in
     no particular order.  An overlay contains position POS if it
     begins at or before POS, and ends after POS.

     To illustrate usage, here is a Lisp function that returns a list
     of the overlays that specify property PROP for the character at
     point:

          (defun find-overlays-specifying (prop)
            (let ((overlays (overlays-at (point)))
                  found)
              (while overlays
                (let ((overlay (car overlays)))
                  (if (overlay-get overlay prop)
                      (setq found (cons overlay found))))
                (setq overlays (cdr overlays)))
              found))

 -- Function: overlays-in beg end
     This function returns a list of the overlays that overlap the
     region BEG through END.  "Overlap" means that at least one
     character is contained within the overlay and also contained
     within the specified region; however, empty overlays are included
     in the result if they are located at BEG, strictly between BEG and
     END, or at END when END denotes the position at the end of the
     buffer.

 -- Function: next-overlay-change pos
     This function returns the buffer position of the next beginning or
     end of an overlay, after POS.  If there is none, it returns
     `(point-max)'.

 -- Function: previous-overlay-change pos
     This function returns the buffer position of the previous
     beginning or end of an overlay, before POS.  If there is none, it
     returns `(point-min)'.

   As an example, here's a simplified (and inefficient) version of the
primitive function `next-single-char-property-change' (*note Property
Search::).  It searches forward from position POS for the next position
where the value of a given property `prop', as obtained from either
overlays or text properties, changes.

     (defun next-single-char-property-change (position prop)
       (save-excursion
         (goto-char position)
         (let ((propval (get-char-property (point) prop)))
           (while (and (not (eobp))
                       (eq (get-char-property (point) prop) propval))
             (goto-char (min (next-overlay-change (point))
                             (next-single-property-change (point) prop)))))
         (point)))


File: elisp,  Node: Width,  Next: Line Height,  Prev: Overlays,  Up: Display

38.10 Width
===========

Since not all characters have the same width, these functions let you
check the width of a character.  *Note Primitive Indent::, and *note
Screen Lines::, for related functions.

 -- Function: char-width char
     This function returns the width in columns of the character CHAR,
     if it were displayed in the current buffer (i.e. taking into
     account the buffer's display table, if any; *note Display
     Tables::).  The width of a tab character is usually `tab-width'
     (*note Usual Display::).

 -- Function: string-width string
     This function returns the width in columns of the string STRING,
     if it were displayed in the current buffer and the selected window.

 -- Function: truncate-string-to-width string width &optional
          start-column padding ellipsis
     This function returns the part of STRING that fits within WIDTH
     columns, as a new string.

     If STRING does not reach WIDTH, then the result ends where STRING
     ends.  If one multi-column character in STRING extends across the
     column WIDTH, that character is not included in the result.  Thus,
     the result can fall short of WIDTH but cannot go beyond it.

     The optional argument START-COLUMN specifies the starting column.
     If this is non-`nil', then the first START-COLUMN columns of the
     string are omitted from the value.  If one multi-column character
     in STRING extends across the column START-COLUMN, that character
     is not included.

     The optional argument PADDING, if non-`nil', is a padding
     character added at the beginning and end of the result string, to
     extend it to exactly WIDTH columns.  The padding character is used
     at the end of the result if it falls short of WIDTH.  It is also
     used at the beginning of the result if one multi-column character
     in STRING extends across the column START-COLUMN.

     If ELLIPSIS is non-`nil', it should be a string which will replace
     the end of STR (including any padding) if it extends beyond
     END-COLUMN, unless the display width of STR is equal to or less
     than the display width of ELLIPSIS.  If ELLIPSIS is non-`nil' and
     not a string, it stands for `"..."'.

          (truncate-string-to-width "\tab\t" 12 4)
               => "ab"
          (truncate-string-to-width "\tab\t" 12 4 ?\s)
               => "    ab  "


File: elisp,  Node: Line Height,  Next: Faces,  Prev: Width,  Up: Display

38.11 Line Height
=================

The total height of each display line consists of the height of the
contents of the line, plus optional additional vertical line spacing
above or below the display line.

   The height of the line contents is the maximum height of any
character or image on that display line, including the final newline if
there is one.  (A display line that is continued doesn't include a
final newline.)  That is the default line height, if you do nothing to
specify a greater height.  (In the most common case, this equals the
height of the default frame font.)

   There are several ways to explicitly specify a larger line height,
either by specifying an absolute height for the display line, or by
specifying vertical space.  However, no matter what you specify, the
actual line height can never be less than the default.

   A newline can have a `line-height' text or overlay property that
controls the total height of the display line ending in that newline.

   If the property value is `t', the newline character has no effect on
the displayed height of the line--the visible contents alone determine
the height.  This is useful for tiling small images (or image slices)
without adding blank areas between the images.

   If the property value is a list of the form `(HEIGHT TOTAL)', that
adds extra space _below_ the display line.  First Emacs uses HEIGHT as
a height spec to control extra space _above_ the line; then it adds
enough space _below_ the line to bring the total line height up to
TOTAL.  In this case, the other ways to specify the line spacing are
ignored.

   Any other kind of property value is a height spec, which translates
into a number--the specified line height.  There are several ways to
write a height spec; here's how each of them translates into a number:

`INTEGER'
     If the height spec is a positive integer, the height value is that
     integer.

`FLOAT'
     If the height spec is a float, FLOAT, the numeric height value is
     FLOAT times the frame's default line height.

`(FACE . RATIO)'
     If the height spec is a cons of the format shown, the numeric
     height is RATIO times the height of face FACE.  RATIO can be any
     type of number, or `nil' which means a ratio of 1.  If FACE is
     `t', it refers to the current face.

`(nil . RATIO)'
     If the height spec is a cons of the format shown, the numeric
     height is RATIO times the height of the contents of the line.

   Thus, any valid height spec determines the height in pixels, one way
or another.  If the line contents' height is less than that, Emacs adds
extra vertical space above the line to achieve the specified total
height.

   If you don't specify the `line-height' property, the line's height
consists of the contents' height plus the line spacing.  There are
several ways to specify the line spacing for different parts of Emacs
text.

   On graphical terminals, you can specify the line spacing for all
lines in a frame, using the `line-spacing' frame parameter (*note
Layout Parameters::).  However, if the default value of `line-spacing'
is non-`nil', it overrides the frame's `line-spacing' parameter.  An
integer value specifies the number of pixels put below lines.  A
floating point number specifies the spacing relative to the frame's
default line height.

   You can specify the line spacing for all lines in a buffer via the
buffer-local `line-spacing' variable.  An integer value specifies the
number of pixels put below lines.  A floating point number specifies
the spacing relative to the default frame line height.  This overrides
line spacings specified for the frame.

   Finally, a newline can have a `line-spacing' text or overlay
property that overrides the default frame line spacing and the buffer
local `line-spacing' variable, for the display line ending in that
newline.

   One way or another, these mechanisms specify a Lisp value for the
spacing of each line.  The value is a height spec, and it translates
into a Lisp value as described above.  However, in this case the
numeric height value specifies the line spacing, rather than the line
height.

   On text terminals, the line spacing cannot be altered.


File: elisp,  Node: Faces,  Next: Fringes,  Prev: Line Height,  Up: Display

38.12 Faces
===========

A "face" is a collection of graphical "attributes" for displaying text:
font, foreground color, background color, optional underlining, and so
on.  Faces control how Emacs displays text in buffers, as well as other
parts of the frame such as the mode line.  *Note Standard Faces:
(emacs)Standard Faces, for the list of faces Emacs normally comes with.

   For most purposes, you refer to a face in Lisp programs using its
"face name", which is usually a Lisp symbol.  For backward
compatibility, a face name can also be a string, which is equivalent to
a Lisp symbol of the same name.

 -- Function: facep object
     This function returns a non-`nil' value if OBJECT is a Lisp symbol
     or string that names a face.  Otherwise, it returns `nil'.

   By default, each face name corresponds to the same set of attributes
in all frames.  But you can also assign a face name a special set of
attributes in one frame (*note Attribute Functions::).

* Menu:

* Defining Faces::      How to define a face.
* Face Attributes::     What is in a face?
* Attribute Functions::  Functions to examine and set face attributes.
* Displaying Faces::     How Emacs combines the faces specified for a character.
* Face Remapping::      Remapping faces to alternative definitions.
* Face Functions::      How to define and examine faces.
* Auto Faces::          Hook for automatic face assignment.
* Basic Faces::         Faces that are defined by default.
* Font Selection::      Finding the best available font for a face.
* Font Lookup::         Looking up the names of available fonts
                          and information about them.
* Fontsets::            A fontset is a collection of fonts
                          that handle a range of character sets.
* Low-Level Font::      Lisp representation for character display fonts.


File: elisp,  Node: Defining Faces,  Next: Face Attributes,  Up: Faces

38.12.1 Defining Faces
----------------------

The `defface' macro defines a face and specifies its default
appearance.  The user can subsequently customize the face using the
Customize interface (*note Customization::).

 -- Macro: defface face spec doc [keyword value]...
     This macro declares FACE as a customizable face whose default
     attributes are given by SPEC.  You should not quote the symbol
     FACE, and it should not end in `-face' (that would be redundant).
     The argument DOC is a documentation string for the face.  The
     additional KEYWORD arguments have the same meanings as in
     `defgroup' and `defcustom' (*note Common Keywords::).

     When `defface' executes, it defines the face according to SPEC,
     then uses any customizations that were read from the init file
     (*note Init File::) to override that specification.

     When you evaluate a `defface' form with `C-M-x' in Emacs Lisp mode
     (`eval-defun'), a special feature of `eval-defun' overrides any
     customizations of the face.  This way, the face reflects exactly
     what the `defface' says.

     The SPEC argument is a "face specification", which states how the
     face should appear on different kinds of terminals.  It should be
     an alist whose elements each have the form `(DISPLAY ATTS)'.
     DISPLAY specifies a class of terminals (see below), while ATTS is
     a property list of face attributes and their values, specifying
     the appearance of the face on matching terminals (*note Face
     Attributes::, for details about face attributes).

     The DISPLAY part of an element of SPEC determines which frames the
     element matches.  If more than one element of SPEC matches a given
     frame, the first element that matches is the one used for that
     frame.  There are three possibilities for DISPLAY:

    `default'
          This element of SPEC doesn't match any frames; instead, it
          specifies defaults that apply to all frames.  This kind of
          element, if used, must be the first element of SPEC.  Each of
          the following elements can override any or all of these
          defaults.

    `t'
          This element of SPEC matches all frames.  Therefore, any
          subsequent elements of SPEC are never used.  Normally `t' is
          used in the last (or only) element of SPEC.

    a list
          If DISPLAY is a list, each element should have the form
          `(CHARACTERISTIC VALUE...)'.  Here CHARACTERISTIC specifies a
          way of classifying frames, and the VALUEs are possible
          classifications which DISPLAY should apply to.  Here are the
          possible values of CHARACTERISTIC:

         `type'
               The kind of window system the frame uses--either
               `graphic' (any graphics-capable display), `x', `pc' (for
               the MS-DOS console), `w32' (for MS Windows 9X/NT/2K/XP),
               or `tty' (a non-graphics-capable display).  *Note
               window-system: Window Systems.

         `class'
               What kinds of colors the frame supports--either `color',
               `grayscale', or `mono'.

         `background'
               The kind of background--either `light' or `dark'.

         `min-colors'
               An integer that represents the minimum number of colors
               the frame should support.  This matches a frame if its
               `display-color-cells' value is at least the specified
               integer.

         `supports'
               Whether or not the frame can display the face attributes
               given in VALUE... (*note Face Attributes::).  *Note
               Display Face Attribute Testing::, for more information
               on exactly how this testing is done.

          If an element of DISPLAY specifies more than one VALUE for a
          given CHARACTERISTIC, any of those values is acceptable.  If
          DISPLAY has more than one element, each element should
          specify a different CHARACTERISTIC; then _each_
          characteristic of the frame must match one of the VALUEs
          specified for it in DISPLAY.

   Here's how the standard face `highlight' is defined:

     (defface highlight
       '((((class color) (min-colors 88) (background light))
          :background "darkseagreen2")
         (((class color) (min-colors 88) (background dark))
          :background "darkolivegreen")
         (((class color) (min-colors 16) (background light))
          :background "darkseagreen2")
         (((class color) (min-colors 16) (background dark))
          :background "darkolivegreen")
         (((class color) (min-colors 8))
          :background "green" :foreground "black")
         (t :inverse-video t))
       "Basic face for highlighting."
       :group 'basic-faces)

   Internally, Emacs stores the face's default specification in its
`face-defface-spec' symbol property (*note Property Lists::).  The
`saved-face' property stores the face specification saved by the user,
using the customization buffer; the `customized-face' property stores
the face specification customized for the current session, but not
saved; and the `theme-face' property stores an alist associating the
active customization settings and Custom themes with their
specifications for that face.  The face's documentation string is
stored in the `face-documentation' property.  But normally you should
not try to set any of these properties directly.  *Note Applying
Customizations::, for the `custom-set-faces' function, which is used to
apply customized face settings.

   People are sometimes tempted to create variables whose values
specify a face to use.  In the vast majority of cases, this is not
necessary; it is preferable to simply use faces directly.

 -- User Option: frame-background-mode
     This option, if non-`nil', specifies the background type to use for
     interpreting face definitions.  If it is `dark', then Emacs treats
     all frames as if they had a dark background, regardless of their
     actual background colors.  If it is `light', then Emacs treats all
     frames as if they had a light background.


File: elisp,  Node: Face Attributes,  Next: Attribute Functions,  Prev: Defining Faces,  Up: Faces

38.12.2 Face Attributes
-----------------------

The effect of using a face is determined by a fixed set of "face
attributes".  This table lists all the face attributes, their possible
values, and their effects.  You can specify more than one face for a
given piece of text; Emacs merges the attributes of all the faces to
determine how to display the text.  *Note Displaying Faces::.

   In addition to the values given below, each face attribute can also
have the value `unspecified'.  This special value means the face
doesn't specify that attribute.  In face merging, when the first face
fails to specify a particular attribute, the next face gets a chance.
However, the `default' face must specify all attributes.

   Some of these attributes are meaningful only on certain kinds of
displays.  If your display cannot handle a certain attribute, the
attribute is ignored.

`:family'
     Font family or fontset (a string).  *Note Fonts: (emacs)Fonts.  If
     you specify a font family name, the wild-card characters `*' and
     `?' are allowed.  The function `font-family-list', described
     below, returns a list of available family names.  *Note
     Fontsets::, for information about fontsets.

`:foundry'
     The name of the "font foundry" for the font family specified by
     the `:family' attribute (a string).  The wild-card characters `*'
     and `?' are allowed.  *Note Fonts: (emacs)Fonts.

`:width'
     Relative character width.  This should be one of the symbols
     `ultra-condensed', `extra-condensed', `condensed',
     `semi-condensed', `normal', `semi-expanded', `expanded',
     `extra-expanded', or `ultra-expanded'.

`:height'
     The height of the font.  In the simplest case, this is an integer
     in units of 1/10 point.

     The value can also be a floating point number or a function, which
     specifies the height relative to an "underlying face" (i.e., a
     face that has a lower priority in the list described in *note
     Displaying Faces::).  If the value is a floating point number,
     that specifies the amount by which to scale the height of the
     underlying face.  If the value is a function, that function is
     called with one argument, the height of the underlying face, and
     returns the height of the new face.  If the function is passed an
     integer argument, it must return an integer.

     The height of the default face must be specified using an integer;
     floating point and function values are not allowed.

`:weight'
     Font weight--one of the symbols (from densest to faintest)
     `ultra-bold', `extra-bold', `bold', `semi-bold', `normal',
     `semi-light', `light', `extra-light', or `ultra-light'.  On text
     terminals which support variable-brightness text, any weight
     greater than normal is displayed as extra bright, and any weight
     less than normal is displayed as half-bright.

`:slant'
     Font slant--one of the symbols `italic', `oblique', `normal',
     `reverse-italic', or `reverse-oblique'.  On text terminals that
     support variable-brightness text, slanted text is displayed as
     half-bright.

`:foreground'
     Foreground color, a string.  The value can be a system-defined
     color name, or a hexadecimal color specification.  *Note Color
     Names::.  On black-and-white displays, certain shades of gray are
     implemented by stipple patterns.

`:background'
     Background color, a string.  The value can be a system-defined
     color name, or a hexadecimal color specification.  *Note Color
     Names::.

`:underline'
     Whether or not characters should be underlined, and in what color.
     If the value is `t', underlining uses the foreground color of the
     face.  If the value is a string, underlining uses that color.  The
     value `nil' means do not underline.

`:overline'
     Whether or not characters should be overlined, and in what color.
     The value is used like that of `:underline'.

`:strike-through'
     Whether or not characters should be strike-through, and in what
     color.  The value is used like that of `:underline'.

`:box'
     Whether or not a box should be drawn around characters, its color,
     the width of the box lines, and 3D appearance.  Here are the
     possible values of the `:box' attribute, and what they mean:

    `nil'
          Don't draw a box.

    `t'
          Draw a box with lines of width 1, in the foreground color.

    COLOR
          Draw a box with lines of width 1, in color COLOR.

    `(:line-width WIDTH :color COLOR :style STYLE)'
          This way you can explicitly specify all aspects of the box.
          The value WIDTH specifies the width of the lines to draw; it
          defaults to 1.  A negative width -N means to draw a line of
          width N that occupies the space of the underlying text, thus
          avoiding any increase in the character height or width.

          The value COLOR specifies the color to draw with.  The
          default is the foreground color of the face for simple boxes,
          and the background color of the face for 3D boxes.

          The value STYLE specifies whether to draw a 3D box.  If it is
          `released-button', the box looks like a 3D button that is not
          being pressed.  If it is `pressed-button', the box looks like
          a 3D button that is being pressed.  If it is `nil' or
          omitted, a plain 2D box is used.

`:inverse-video'
     Whether or not characters should be displayed in inverse video.
     The value should be `t' (yes) or `nil' (no).

`:stipple'
     The background stipple, a bitmap.

     The value can be a string; that should be the name of a file
     containing external-format X bitmap data.  The file is found in
     the directories listed in the variable `x-bitmap-file-path'.

     Alternatively, the value can specify the bitmap directly, with a
     list of the form `(WIDTH HEIGHT DATA)'.  Here, WIDTH and HEIGHT
     specify the size in pixels, and DATA is a string containing the
     raw bits of the bitmap, row by row.  Each row occupies (WIDTH + 7)
     / 8 consecutive bytes in the string (which should be a unibyte
     string for best results).  This means that each row always
     occupies at least one whole byte.

     If the value is `nil', that means use no stipple pattern.

     Normally you do not need to set the stipple attribute, because it
     is used automatically to handle certain shades of gray.

`:font'
     The font used to display the face.  Its value should be a font
     object.  *Note Font Selection::, for information about font
     objects.

     When specifying this attribute using `set-face-attribute' (*note
     Attribute Functions::), you may also supply a font spec, a font
     entity, or a string.  Emacs converts such values to an appropriate
     font object, and stores that font object as the actual attribute
     value.  If you specify a string, the contents of the string should
     be a font name (*note Fonts: (emacs)Fonts.); if the font name is
     an XLFD containing wildcards, Emacs chooses the first font
     matching those wildcards.  Specifying this attribute also changes
     the values of the `:family', `:foundry', `:width', `:height',
     `:weight', and `:slant' attributes.

`:inherit'
     The name of a face from which to inherit attributes, or a list of
     face names.  Attributes from inherited faces are merged into the
     face like an underlying face would be, with higher priority than
     underlying faces (*note Displaying Faces::).  If a list of faces
     is used, attributes from faces earlier in the list override those
     from later faces.

   For compatibility with Emacs 20, you can also specify values for two
"fake" face attributes: `:bold' and `:italic'.  Their values must be
either `t' or `nil'; a value of `unspecified' is not allowed.  Setting
`:bold' to `t' is equivalent to setting the `:weight' attribute to
`bold', and setting it to `nil' is equivalent to setting `:weight' to
`normal'.  Setting `:italic' to `t' is equivalent to setting the
`:slant' attribute to `italic', and setting it to `nil' is equivalent
to setting `:slant' to `normal'.

 -- Function: font-family-list &optional frame
     This function returns a list of available font family names.  The
     optional argument FRAME specifies the frame on which the text is
     to be displayed; if it is `nil', the selected frame is used.

 -- User Option: underline-minimum-offset
     This variable specifies the minimum distance between the baseline
     and the underline, in pixels, when displaying underlined text.

 -- User Option: x-bitmap-file-path
     This variable specifies a list of directories for searching for
     bitmap files, for the `:stipple' attribute.

 -- Function: bitmap-spec-p object
     This returns `t' if OBJECT is a valid bitmap specification,
     suitable for use with `:stipple' (see above).  It returns `nil'
     otherwise.


File: elisp,  Node: Attribute Functions,  Next: Displaying Faces,  Prev: Face Attributes,  Up: Faces

38.12.3 Face Attribute Functions
--------------------------------

This section describes the functions for accessing and modifying the
attributes of an existing face.

 -- Function: set-face-attribute face frame &rest arguments
     This function sets one or more attributes of FACE for FRAME.  The
     attributes you specify this way override whatever the `defface'
     says.

     The extra arguments ARGUMENTS specify the attributes to set, and
     the values for them.  They should consist of alternating attribute
     names (such as `:family' or `:underline') and values.  Thus,

          (set-face-attribute 'foo nil
                              :width 'extended
                              :weight 'bold)

     sets the attribute `:width' to `extended' and the attribute
     `:weight' to `bold'.

     If FRAME is `t', this function sets the default attributes for new
     frames.  Default attribute values specified this way override the
     `defface' for newly created frames.

     If FRAME is `nil', this function sets the attributes for all
     existing frames, and the default for new frames.

 -- Function: face-attribute face attribute &optional frame inherit
     This returns the value of the ATTRIBUTE attribute of FACE on
     FRAME.  If FRAME is `nil', that means the selected frame (*note
     Input Focus::).

     If FRAME is `t', this returns whatever new-frames default value
     you previously specified with `set-face-attribute' for the
     ATTRIBUTE attribute of FACE.  If you have not specified one, it
     returns `nil'.

     If INHERIT is `nil', only attributes directly defined by FACE are
     considered, so the return value may be `unspecified', or a
     relative value.  If INHERIT is non-`nil', FACE's definition of
     ATTRIBUTE is merged with the faces specified by its `:inherit'
     attribute; however the return value may still be `unspecified' or
     relative.  If INHERIT is a face or a list of faces, then the
     result is further merged with that face (or faces), until it
     becomes specified and absolute.

     To ensure that the return value is always specified and absolute,
     use a value of `default' for INHERIT; this will resolve any
     unspecified or relative values by merging with the `default' face
     (which is always completely specified).

     For example,

          (face-attribute 'bold :weight)
               => bold

 -- Function: face-attribute-relative-p attribute value
     This function returns non-`nil' if VALUE, when used as the value
     of the face attribute ATTRIBUTE, is relative.  This means it would
     modify, rather than completely override, any value that comes from
     a subsequent face in the face list or that is inherited from
     another face.

     `unspecified' is a relative value for all attributes.  For
     `:height', floating point and function values are also relative.

     For example:

          (face-attribute-relative-p :height 2.0)
               => t

 -- Function: face-all-attributes face &optional frame
     This function returns an alist of attributes of FACE.  The
     elements of the result are name-value pairs of the form
     `(ATTR-NAME . ATTR-VALUE)'.  Optional argument FRAME specifies the
     frame whose definition of FACE to return; if omitted or `nil', the
     returned value describes the default attributes of FACE for newly
     created frames.

 -- Function: merge-face-attribute attribute value1 value2
     If VALUE1 is a relative value for the face attribute ATTRIBUTE,
     returns it merged with the underlying value VALUE2; otherwise, if
     VALUE1 is an absolute value for the face attribute ATTRIBUTE,
     returns VALUE1 unchanged.

   The following commands and functions mostly provide compatibility
with old versions of Emacs.  They work by calling `set-face-attribute'.
Values of `t' and `nil' for their FRAME argument are handled just like
`set-face-attribute' and `face-attribute'.  The commands read their
arguments using the minibuffer, if called interactively.

 -- Command: set-face-foreground face color &optional frame
 -- Command: set-face-background face color &optional frame
     These set the `:foreground' attribute (or `:background' attribute,
     respectively) of FACE to COLOR.

 -- Command: set-face-stipple face pattern &optional frame
     This sets the `:stipple' attribute of FACE to PATTERN.

 -- Command: set-face-font face font &optional frame
     This sets the `:font' attribute of FACE to FONT.

 -- Function: set-face-bold-p face bold-p &optional frame
     This sets the `:weight' attribute of FACE to NORMAL if BOLD-P is
     `nil', and to BOLD otherwise.

 -- Function: set-face-italic-p face italic-p &optional frame
     This sets the `:slant' attribute of FACE to NORMAL if ITALIC-P is
     `nil', and to ITALIC otherwise.

 -- Function: set-face-underline-p face underline &optional frame
     This sets the `:underline' attribute of FACE to UNDERLINE.

 -- Function: set-face-inverse-video-p face inverse-video-p &optional
          frame
     This sets the `:inverse-video' attribute of FACE to
     INVERSE-VIDEO-P.

 -- Command: invert-face face &optional frame
     This swaps the foreground and background colors of face FACE.

   The following functions examine the attributes of a face.  If you
don't specify FRAME, they refer to the selected frame; `t' refers to
the default data for new frames.  They return the symbol `unspecified'
if the face doesn't define any value for that attribute.

 -- Function: face-foreground face &optional frame inherit
 -- Function: face-background face &optional frame inherit
     These functions return the foreground color (or background color,
     respectively) of face FACE, as a string.

     If INHERIT is `nil', only a color directly defined by the face is
     returned.  If INHERIT is non-`nil', any faces specified by its
     `:inherit' attribute are considered as well, and if INHERIT is a
     face or a list of faces, then they are also considered, until a
     specified color is found.  To ensure that the return value is
     always specified, use a value of `default' for INHERIT.

 -- Function: face-stipple face &optional frame inherit
     This function returns the name of the background stipple pattern
     of face FACE, or `nil' if it doesn't have one.

     If INHERIT is `nil', only a stipple directly defined by the face
     is returned.  If INHERIT is non-`nil', any faces specified by its
     `:inherit' attribute are considered as well, and if INHERIT is a
     face or a list of faces, then they are also considered, until a
     specified stipple is found.  To ensure that the return value is
     always specified, use a value of `default' for INHERIT.

 -- Function: face-font face &optional frame
     This function returns the name of the font of face FACE.

 -- Function: face-bold-p face &optional frame
     This function returns a non-`nil' value if the `:weight' attribute
     of FACE is bolder than normal (i.e., one of `semi-bold', `bold',
     `extra-bold', or `ultra-bold').  Otherwise, it returns `nil'.

 -- Function: face-italic-p face &optional frame
     This function returns a non-`nil' value if the `:slant' attribute
     of FACE is `italic' or `oblique', and `nil' otherwise.

 -- Function: face-underline-p face &optional frame
     This function returns the `:underline' attribute of face FACE.

 -- Function: face-inverse-video-p face &optional frame
     This function returns the `:inverse-video' attribute of face FACE.


File: elisp,  Node: Displaying Faces,  Next: Face Remapping,  Prev: Attribute Functions,  Up: Faces

38.12.4 Displaying Faces
------------------------

Here is how Emacs determines the face to use for displaying any given
piece of text:

   * If the text consists of a special glyph, the glyph can specify a
     particular face.  *Note Glyphs::.

   * If the text lies within an active region, Emacs highlights it using
     the `region' face.  *Note Standard Faces: (emacs)Standard Faces.

   * If the text lies within an overlay with a non-`nil' `face'
     property, Emacs applies the face or face attributes specified by
     that property.  If the overlay has a `mouse-face' property and the
     mouse is "near enough" to the overlay, Emacs applies the face or
     face attributes specified by the `mouse-face' property instead.
     *Note Overlay Properties::.

     When multiple overlays cover one character, an overlay with higher
     priority overrides those with lower priority.  *Note Overlays::.

   * If the text contains a `face' or `mouse-face' property, Emacs
     applies the specified faces and face attributes.  *Note Special
     Properties::.  (This is how Font Lock mode faces are applied.
     *Note Font Lock Mode::.)

   * If the text lies within the mode line of the selected window, Emacs
     applies the `mode-line' face.  For the mode line of a non-selected
     window, Emacs applies the `mode-line-inactive' face.  For a header
     line, Emacs applies the `header-line' face.

   * If any given attribute has not been specified during the preceding
     steps, Emacs applies the attribute of the `default' face.

   If these various sources together specify more than one face for a
particular character, Emacs merges the attributes of the various faces
specified.  For each attribute, Emacs tries using the above order (i.e.
first the face of any special glyph; then the face for region
highlighting, if appropriate; and so on).


File: elisp,  Node: Face Remapping,  Next: Face Functions,  Prev: Displaying Faces,  Up: Faces

38.12.5 Face Remapping
----------------------

The variable `face-remapping-alist' is used for buffer-local or global
changes in the appearance of a face.  For instance, it is used to
implement the `text-scale-adjust' command (*note Text Scale:
(emacs)Text Scale.).

 -- Variable: face-remapping-alist
     The value of this variable is an alist whose elements have the form
     `(FACE . REMAPPING)'.  This causes Emacs to display any text
     having the face FACE with REMAPPING, rather than the ordinary
     definition of FACE.  REMAPPING may be any face specification
     suitable for a `face' text property: either a face name, or a
     property list of attribute/value pairs, or a list in which each
     element is either a face name or a property list (*note Special
     Properties::).

     If `face-remapping-alist' is buffer-local, its local value takes
     effect only within that buffer.

     Two points bear emphasizing:

       1. REMAPPING serves as the complete specification for the
          remapped face--it replaces the normal definition of FACE,
          instead of modifying it.

       2. If REMAPPING references the same face name FACE, either
          directly or via the `:inherit' attribute of some other face in
          REMAPPING, that reference uses the normal definition of FACE.
          In other words, the remapping cannot be recursive.

          For instance, if the `mode-line' face is remapped using this
          entry in `face-remapping-alist':
               (mode-line italic mode-line)
          then the new definition of the `mode-line' face inherits from
          the `italic' face, and the _normal_ (non-remapped) definition
          of `mode-line' face.

   The following functions implement a higher-level interface to
`face-remapping-alist'.  Most Lisp code should use these functions
instead of setting `face-remapping-alist' directly, to avoid trampling
on remappings applied elsewhere.  These functions are intended for
buffer-local remappings, so they all make `face-remapping-alist'
buffer-local as a side-effect. They manage `face-remapping-alist'
entries of the form

       (FACE RELATIVE-SPEC-1 RELATIVE-SPEC-2 ... BASE-SPEC)

where, as explained above, each of the RELATIVE-SPEC-N and BASE-SPEC is
either a face name, or a property list of attribute/value pairs.  Each
of the "relative remapping" entries, RELATIVE-SPEC-N, is managed by the
`face-remap-add-relative' and `face-remap-remove-relative' functions;
these are intended for simple modifications like changing the text
size.  The "base remapping" entry, BASE-SPEC, has the lowest priority
and is managed by the `face-remap-set-base' and `face-remap-reset-base'
functions; it is intended for major modes to remap faces in the buffers
they control.

 -- Function: face-remap-add-relative face &rest specs
     This functions adds the face specifications in SPECS as relative
     remappings for face FACE in the current buffer.  The remaining
     arguments, SPECS, should form either a list of face names, or a
     property list of attribute/value pairs.

     The return value is a Lisp object that serves as a "cookie"; you
     can pass this object as an argument to `face-remap-remove-relative'
     if you need to remove the remapping later.

          ;; Remap the `escape-glyph' face into a combination
          ;; of the `highlight' and `italic' faces:
          (face-remap-add-relative 'escape-glyph 'highlight 'italic)

          ;; Increase the size of the `default' face by 50%:
          (face-remap-add-relative 'default :height 1.5)

 -- Function: face-remap-remove-relative cookie
     This function removes a relative remapping previously added by
     `face-remap-add-relative'.  COOKIE should be the Lisp object
     returned by `face-remap-add-relative' when the remapping was added.

 -- Function: face-remap-set-base face &rest specs
     This function sets the base remapping of FACE in the current
     buffer to SPECS.  If SPECS is empty, the default base remapping is
     restored, similar to calling `face-remap-reset-base' (see below);
     note that this is different from SPECS containing a single value
     `nil', which has the opposite result (the global definition of
     FACE is ignored).

     This overwrites the default BASE-SPEC, which inherits the global
     face definition, so it is up to the caller to add such inheritance
     if so desired.

 -- Function: face-remap-reset-base face
     This function sets the base remapping of FACE to its default
     value, which inherits from FACE's global definition.


File: elisp,  Node: Face Functions,  Next: Auto Faces,  Prev: Face Remapping,  Up: Faces

38.12.6 Functions for Working with Faces
----------------------------------------

Here are additional functions for creating and working with faces.

 -- Function: face-list
     This function returns a list of all defined face names.

 -- Function: face-id face
     This function returns the "face number" of face FACE.  This is a
     number that uniquely identifies a face at low levels within Emacs.
     It is seldom necessary to refer to a face by its face number.

 -- Function: face-documentation face
     This function returns the documentation string of face FACE, or
     `nil' if none was specified for it.

 -- Function: face-equal face1 face2 &optional frame
     This returns `t' if the faces FACE1 and FACE2 have the same
     attributes for display.

 -- Function: face-differs-from-default-p face &optional frame
     This returns non-`nil' if the face FACE displays differently from
     the default face.

   A "face alias" provides an equivalent name for a face.  You can
define a face alias by giving the alias symbol the `face-alias'
property, with a value of the target face name.  The following example
makes `modeline' an alias for the `mode-line' face.

     (put 'modeline 'face-alias 'mode-line)

 -- Macro: define-obsolete-face-alias obsolete-face current-face when
     This macro defines `obsolete-face' as an alias for CURRENT-FACE,
     and also marks it as obsolete, indicating that it may be removed
     in future.  WHEN should be a string indicating when
     `obsolete-face' was made obsolete (usually a version number
     string).


File: elisp,  Node: Auto Faces,  Next: Basic Faces,  Prev: Face Functions,  Up: Faces

38.12.7 Automatic Face Assignment
---------------------------------

This hook is used for automatically assigning faces to text in the
buffer.  It is part of the implementation of Jit-Lock mode, used by
Font-Lock.

 -- Variable: fontification-functions
     This variable holds a list of functions that are called by Emacs
     redisplay as needed, just before doing redisplay.  They are called
     even when Font Lock Mode isn't enabled.  When Font Lock Mode is
     enabled, this variable usually holds just one function,
     `jit-lock-function'.

     The functions are called in the order listed, with one argument, a
     buffer position POS.  Collectively they should attempt to assign
     faces to the text in the current buffer starting at POS.

     The functions should record the faces they assign by setting the
     `face' property.  They should also add a non-`nil' `fontified'
     property to all the text they have assigned faces to.  That
     property tells redisplay that faces have been assigned to that text
     already.

     It is probably a good idea for the functions to do nothing if the
     character after POS already has a non-`nil' `fontified' property,
     but this is not required.  If one function overrides the
     assignments made by a previous one, the properties after the last
     function finishes are the ones that really matter.

     For efficiency, we recommend writing these functions so that they
     usually assign faces to around 400 to 600 characters at each call.


File: elisp,  Node: Basic Faces,  Next: Font Selection,  Prev: Auto Faces,  Up: Faces

38.12.8 Basic Faces
-------------------

If your Emacs Lisp program needs to assign some faces to text, it is
often a good idea to use certain existing faces or inherit from them,
rather than defining entirely new faces.  This way, if other users have
customized the basic faces to give Emacs a certain look, your program
will "fit in" without additional customization.

   Some of the basic faces defined in Emacs are listed below.  In
addition to these, you might want to make use of the Font Lock faces
for syntactic highlighting, if highlighting is not already handled by
Font Lock mode, or if some Font Lock faces are not in use.  *Note Faces
for Font Lock::.

`default'
     The default face, whose attributes are all specified.  All other
     faces implicitly inherit from it: any unspecified attribute
     defaults to the attribute on this face (*note Face Attributes::).

`bold'
`italic'
`bold-italic'
`underline'
`fixed-pitch'
`variable-pitch'
     These have the attributes indicated by their names (e.g. `bold'
     has a bold `:weight' attribute), with all other attributes
     unspecified (and so given by `default').

`shadow'
     For "dimmed out" text.  For example, it is used for the ignored
     part of a filename in the minibuffer (*note Minibuffers for File
     Names: (emacs)Minibuffer File.).

`link'
`link-visited'
     For clickable text buttons that send the user to a different
     buffer or "location".

`highlight'
     For stretches of text that should temporarily stand out.  For
     example, it is commonly assigned to the `mouse-face' property for
     cursor highlighting (*note Special Properties::).

`match'
     For text matching a search command.

`error'
`warning'
`success'
     For text concerning errors, warnings, or successes.  For example,
     these are used for messages in `*Compilation*' buffers.


File: elisp,  Node: Font Selection,  Next: Font Lookup,  Prev: Basic Faces,  Up: Faces

38.12.9 Font Selection
----------------------

Before Emacs can draw a character on a graphical display, it must
select a "font" for that character(1).  *Note Fonts: (emacs)Fonts.
Normally, Emacs automatically chooses a font based on the faces
assigned to that character--specifically, the face attributes `:family',
`:weight', `:slant', and `:width' (*note Face Attributes::).  The
choice of font also depends on the character to be displayed; some
fonts can only display a limited set of characters.  If no available
font exactly fits the requirements, Emacs looks for the "closest
matching font".  The variables in this section control how Emacs makes
this selection.

 -- User Option: face-font-family-alternatives
     If a given family is specified but does not exist, this variable
     specifies alternative font families to try.  Each element should
     have this form:

          (FAMILY ALTERNATE-FAMILIES...)

     If FAMILY is specified but not available, Emacs will try the other
     families given in ALTERNATE-FAMILIES, one by one, until it finds a
     family that does exist.

 -- User Option: face-font-selection-order
     If there is no font that exactly matches all desired face
     attributes (`:width', `:height', `:weight', and `:slant'), this
     variable specifies the order in which these attributes should be
     considered when selecting the closest matching font.  The value
     should be a list containing those four attribute symbols, in order
     of decreasing importance.  The default is `(:width :height :weight
     :slant)'.

     Font selection first finds the best available matches for the first
     attribute in the list; then, among the fonts which are best in that
     way, it searches for the best matches in the second attribute, and
     so on.

     The attributes `:weight' and `:width' have symbolic values in a
     range centered around `normal'.  Matches that are more extreme
     (farther from `normal') are somewhat preferred to matches that are
     less extreme (closer to `normal'); this is designed to ensure that
     non-normal faces contrast with normal ones, whenever possible.

     One example of a case where this variable makes a difference is
     when the default font has no italic equivalent.  With the default
     ordering, the `italic' face will use a non-italic font that is
     similar to the default one.  But if you put `:slant' before
     `:height', the `italic' face will use an italic font, even if its
     height is not quite right.

 -- User Option: face-font-registry-alternatives
     This variable lets you specify alternative font registries to try,
     if a given registry is specified and doesn't exist.  Each element
     should have this form:

          (REGISTRY ALTERNATE-REGISTRIES...)

     If REGISTRY is specified but not available, Emacs will try the
     other registries given in ALTERNATE-REGISTRIES, one by one, until
     it finds a registry that does exist.

   Emacs can make use of scalable fonts, but by default it does not use
them.

 -- User Option: scalable-fonts-allowed
     This variable controls which scalable fonts to use.  A value of
     `nil', the default, means do not use scalable fonts.  `t' means to
     use any scalable font that seems appropriate for the text.

     Otherwise, the value must be a list of regular expressions.  Then a
     scalable font is enabled for use if its name matches any regular
     expression in the list.  For example,

          (setq scalable-fonts-allowed '("muleindian-2$"))

     allows the use of scalable fonts with registry `muleindian-2'.

 -- Variable: face-font-rescale-alist
     This variable specifies scaling for certain faces.  Its value
     should be a list of elements of the form

          (FONTNAME-REGEXP . SCALE-FACTOR)

     If FONTNAME-REGEXP matches the font name that is about to be used,
     this says to choose a larger similar font according to the factor
     SCALE-FACTOR.  You would use this feature to normalize the font
     size if certain fonts are bigger or smaller than their nominal
     heights and widths would suggest.

   ---------- Footnotes ----------

   (1) In this context, the term "font" has nothing to do with Font
Lock (*note Font Lock Mode::).


File: elisp,  Node: Font Lookup,  Next: Fontsets,  Prev: Font Selection,  Up: Faces

38.12.10 Looking Up Fonts
-------------------------

 -- Function: x-list-fonts name &optional reference-face frame maximum
          width
     This function returns a list of available font names that match
     NAME.  NAME should be a string containing a font name in either
     the Fontconfig, GTK, or XLFD format (*note Fonts: (emacs)Fonts.).
     Within an XLFD string, wildcard characters may be used: the `*'
     character matches any substring, and the `?' character matches any
     single character.  Case is ignored when matching font names.

     If the optional arguments REFERENCE-FACE and FRAME are specified,
     the returned list includes only fonts that are the same size as
     REFERENCE-FACE (a face name) currently is on the frame FRAME.

     The optional argument MAXIMUM sets a limit on how many fonts to
     return.  If it is non-`nil', then the return value is truncated
     after the first MAXIMUM matching fonts.  Specifying a small value
     for MAXIMUM can make this function much faster, in cases where
     many fonts match the pattern.

     The optional argument WIDTH specifies a desired font width.  If it
     is non-`nil', the function only returns those fonts whose
     characters are (on average) WIDTH times as wide as REFERENCE-FACE.

 -- Function: x-family-fonts &optional family frame
     This function returns a list describing the available fonts for
     family FAMILY on FRAME.  If FAMILY is omitted or `nil', this list
     applies to all families, and therefore, it contains all available
     fonts.  Otherwise, FAMILY must be a string; it may contain the
     wildcards `?' and `*'.

     The list describes the display that FRAME is on; if FRAME is
     omitted or `nil', it applies to the selected frame's display
     (*note Input Focus::).

     Each element in the list is a vector of the following form:

          [FAMILY WIDTH POINT-SIZE WEIGHT SLANT
           FIXED-P FULL REGISTRY-AND-ENCODING]

     The first five elements correspond to face attributes; if you
     specify these attributes for a face, it will use this font.

     The last three elements give additional information about the font.
     FIXED-P is non-`nil' if the font is fixed-pitch.  FULL is the full
     name of the font, and REGISTRY-AND-ENCODING is a string giving the
     registry and encoding of the font.

 -- Variable: font-list-limit
     This variable specifies maximum number of fonts to consider in font
     matching.  The function `x-family-fonts' will not return more than
     that many fonts, and font selection will consider only that many
     fonts when searching a matching font for face attributes.  The
     default is currently 100.


File: elisp,  Node: Fontsets,  Next: Low-Level Font,  Prev: Font Lookup,  Up: Faces

38.12.11 Fontsets
-----------------

A "fontset" is a list of fonts, each assigned to a range of character
codes.  An individual font cannot display the whole range of characters
that Emacs supports, but a fontset can.  Fontsets have names, just as
fonts do, and you can use a fontset name in place of a font name when
you specify the "font" for a frame or a face.  Here is information
about defining a fontset under Lisp program control.

 -- Function: create-fontset-from-fontset-spec fontset-spec &optional
          style-variant-p noerror
     This function defines a new fontset according to the specification
     string FONTSET-SPEC.  The string should have this format:

          FONTPATTERN, [CHARSET:FONT]...

     Whitespace characters before and after the commas are ignored.

     The first part of the string, FONTPATTERN, should have the form of
     a standard X font name, except that the last two fields should be
     `fontset-ALIAS'.

     The new fontset has two names, one long and one short.  The long
     name is FONTPATTERN in its entirety.  The short name is
     `fontset-ALIAS'.  You can refer to the fontset by either name.  If
     a fontset with the same name already exists, an error is signaled,
     unless NOERROR is non-`nil', in which case this function does
     nothing.

     If optional argument STYLE-VARIANT-P is non-`nil', that says to
     create bold, italic and bold-italic variants of the fontset as
     well.  These variant fontsets do not have a short name, only a
     long one, which is made by altering FONTPATTERN to indicate the
     bold or italic status.

     The specification string also says which fonts to use in the
     fontset.  See below for the details.

   The construct `CHARSET:FONT' specifies which font to use (in this
fontset) for one particular character set.  Here, CHARSET is the name
of a character set, and FONT is the font to use for that character set.
You can use this construct any number of times in the specification
string.

   For the remaining character sets, those that you don't specify
explicitly, Emacs chooses a font based on FONTPATTERN: it replaces
`fontset-ALIAS' with a value that names one character set.  For the
ASCII character set, `fontset-ALIAS' is replaced with `ISO8859-1'.

   In addition, when several consecutive fields are wildcards, Emacs
collapses them into a single wildcard.  This is to prevent use of
auto-scaled fonts.  Fonts made by scaling larger fonts are not usable
for editing, and scaling a smaller font is not useful because it is
better to use the smaller font in its own size, which Emacs does.

   Thus if FONTPATTERN is this,

     -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24

the font specification for ASCII characters would be this:

     -*-fixed-medium-r-normal-*-24-*-ISO8859-1

and the font specification for Chinese GB2312 characters would be this:

     -*-fixed-medium-r-normal-*-24-*-gb2312*-*

   You may not have any Chinese font matching the above font
specification.  Most X distributions include only Chinese fonts that
have `song ti' or `fangsong ti' in the FAMILY field.  In such a case,
`Fontset-N' can be specified as below:

     Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
             chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*

Then, the font specifications for all but Chinese GB2312 characters have
`fixed' in the FAMILY field, and the font specification for Chinese
GB2312 characters has a wild card `*' in the FAMILY field.

 -- Function: set-fontset-font name character font-spec &optional frame
          add
     This function modifies the existing fontset NAME to use the font
     matching with FONT-SPEC for the character CHARACTER.

     If NAME is `nil', this function modifies the fontset of the
     selected frame or that of FRAME if FRAME is not `nil'.

     If NAME is `t', this function modifies the default fontset, whose
     short name is `fontset-default'.

     CHARACTER may be a cons; `(FROM . TO)', where FROM and TO are
     character codepoints.  In that case, use FONT-SPEC for all
     characters in the range FROM and TO (inclusive).

     CHARACTER may be a charset.  In that case, use FONT-SPEC for all
     character in the charsets.

     CHARACTER may be a script name.  In that case, use FONT-SPEC for
     all character in the charsets.

     FONT-SPEC may be a cons; `(FAMILY . REGISTRY)', where FAMILY is a
     family name of a font (possibly including a foundry name at the
     head), REGISTRY is a registry name of a font (possibly including
     an encoding name at the tail).

     FONT-SPEC may be a font name string.

     The optional argument ADD, if non-`nil', specifies how to add
     FONT-SPEC to the font specifications previously set.  If it is
     `prepend', FONT-SPEC is prepended.  If it is `append', FONT-SPEC
     is appended.  By default, FONT-SPEC overrides the previous
     settings.

     For instance, this changes the default fontset to use a font of
     which family name is `Kochi Gothic' for all characters belonging to
     the charset `japanese-jisx0208'.

          (set-fontset-font t 'japanese-jisx0208
                            (font-spec :family "Kochi Gothic"))

 -- Function: char-displayable-p char
     This function returns `t' if Emacs ought to be able to display
     CHAR.  More precisely, if the selected frame's fontset has a font
     to display the character set that CHAR belongs to.

     Fontsets can specify a font on a per-character basis; when the
     fontset does that, this function's value may not be accurate.


File: elisp,  Node: Low-Level Font,  Prev: Fontsets,  Up: Faces

38.12.12 Low-Level Font Representation
--------------------------------------

Normally, it is not necessary to manipulate fonts directly.  In case
you need to do so, this section explains how.

   In Emacs Lisp, fonts are represented using three different Lisp
object types: "font objects", "font specs", and "font entities".

 -- Function: fontp object &optional type
     Return `t' if OBJECT is a font object, font spec, or font entity.
     Otherwise, return `nil'.

     The optional argument TYPE, if non-`nil', determines the exact
     type of Lisp object to check for.  In that case, TYPE should be
     one of `font-object', `font-spec', or `font-entity'.

   A font object is a Lisp object that represents a font that Emacs has
"opened".  Font objects cannot be modified in Lisp, but they can be
inspected.

 -- Function: font-at position &optional window string
     Return the font object that is being used to display the character
     at position POSITION in the window WINDOW.  If WINDOW is `nil', it
     defaults to the selected window.  If STRING is `nil', POSITION
     specifies a position in the current buffer; otherwise, STRING
     should be a string, and POSITION specifies a position in that
     string.

   A font spec is a Lisp object that contains a set of specifications
that can be used to find a font.  More than one font may match the
specifications in a font spec.

 -- Function: font-spec &rest arguments
     Return a new font spec using the specifications in ARGUMENTS,
     which should come in `property'-`value' pairs.  The possible
     specifications are as follows:

    `:name'
          The font name (a string), in either XLFD, Fontconfig, or GTK
          format.  *Note Fonts: (emacs)Fonts.

    `:family'
    `:foundry'
    `:weight'
    `:slant'
    `:width'
          These have the same meanings as the face attributes of the
          same name.  *Note Face Attributes::.

    `:size'
          The font size--either a non-negative integer that specifies
          the pixel size, or a floating point number that specifies the
          point size.

    `:adstyle'
          Additional typographic style information for the font, such as
          `sans'.  The value should be a string or a symbol.

    `:registry'
          The charset registry and encoding of the font, such as
          `iso8859-1'.  The value should be a string or a symbol.

    `:script'
          The script that the font must support (a symbol).

    `:otf'
          The font must be an OpenType font that supports these OpenType
          features, provided Emacs is compiled with support for
          `libotf' (a library for performing complex text layout in
          certain scripts).  The value must be a list of the form

               `(SCRIPT-TAG LANGSYS-TAG GSUB GPOS)'

          where SCRIPT-TAG is the OpenType script tag symbol;
          LANGSYS-TAG is the OpenType language system tag symbol, or
          `nil' to use the default language system; `gsub' is a list of
          OpenType GSUB feature tag symbols, or `nil' if none is
          required; and `gpos' is a list of OpenType GPOS feature tag
          symbols, or `nil' if none is required.  If `gsub' or `gpos'
          is a list, a `nil' element in that list means that the font
          must not match any of the remaining tag symbols.  The `gpos'
          element may be omitted.

 -- Function: font-put font-spec property value
     Set the font property PROPERTY in the font-spec FONT-SPEC to VALUE.

   A font entity is a reference to a font that need not be open.  Its
properties are intermediate between a font object and a font spec: like
a font object, and unlike a font spec, it refers to a single, specific
font.  Unlike a font object, creating a font entity does not load the
contents of that font into computer memory.

 -- Function: find-font font-spec &optional frame
     This function returns a font entity that best matches the font spec
     FONT-SPEC on frame FRAME.  If FRAME is `nil', it defaults to the
     selected frame.

 -- Function: list-fonts font-spec &optional frame num prefer
     This function returns a list of all font entities that match the
     font spec FONT-SPEC.

     The optional argument FRAME, if non-`nil', specifies the frame on
     which the fonts are to be displayed.  The optional argument NUM,
     if non-`nil', should be an integer that specifies the maximum
     length of the returned list.  The optional argument PREFER, if
     non-`nil', should be another font spec, which is used to control
     the order of the returned list; the returned font entities are
     sorted in order of decreasing "closeness" to that font spec.

   If you call `set-face-attribute' and pass a font spec, font entity,
or font name string as the value of the `:font' attribute, Emacs opens
the best "matching" font that is available for display.  It then stores
the corresponding font object as the actual value of the `:font'
attribute for that face.

   The following functions can be used to obtain information about a
font.  For these functions, the FONT argument can be a font object, a
font entity, or a font spec.

 -- Function: font-get font property
     This function returns the value of the font property PROPERTY for
     FONT.

     If FONT is a font spec and the font spec does not specify
     PROPERTY, the return value is `nil'.  If FONT is a font object or
     font entity, the value for the :SCRIPT property may be a list of
     scripts supported by the font.

 -- Function: font-face-attributes font &optional frame
     This function returns a list of face attributes corresponding to
     FONT.  The optional argument FRAME specifies the frame on which
     the font is to be displayed.  If it is `nil', the selected frame
     is used.  The return value has the form

          (:family FAMILY :height HEIGHT :weight WEIGHT
             :slant SLANT :width WIDTH)

     where the values of FAMILY, HEIGHT, WEIGHT, SLANT, and WIDTH are
     face attribute values.  Some of these key-attribute pairs may be
     omitted from the list if they are not specified by FONT.

 -- Function: font-xlfd-name font &optional fold-wildcards
     This function returns the XLFD (X Logical Font Descriptor), a
     string, matching FONT.  *Note Fonts: (emacs)Fonts, for information
     about XLFDs.  If the name is too long for an XLFD (which can
     contain at most 255 characters), the function returns `nil'.

     If the optional argument FOLD-WILDCARDS is non-`nil', consecutive
     wildcards in the XLFD are folded into one.


File: elisp,  Node: Fringes,  Next: Scroll Bars,  Prev: Faces,  Up: Display

38.13 Fringes
=============

On graphical displays, Emacs draws "fringes" next to each window: thin
vertical strips down the sides which can display bitmaps indicating
truncation, continuation, horizontal scrolling, and so on.

* Menu:

* Fringe Size/Pos::     Specifying where to put the window fringes.
* Fringe Indicators::   Displaying indicator icons in the window fringes.
* Fringe Cursors::      Displaying cursors in the right fringe.
* Fringe Bitmaps::      Specifying bitmaps for fringe indicators.
* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes.
* Overlay Arrow::       Display of an arrow to indicate position.


File: elisp,  Node: Fringe Size/Pos,  Next: Fringe Indicators,  Up: Fringes

38.13.1 Fringe Size and Position
--------------------------------

The following buffer-local variables control the position and width of
fringes in windows showing that buffer.

 -- Variable: fringes-outside-margins
     The fringes normally appear between the display margins and the
     window text.  If the value is non-`nil', they appear outside the
     display margins.  *Note Display Margins::.

 -- Variable: left-fringe-width
     This variable, if non-`nil', specifies the width of the left
     fringe in pixels.  A value of `nil' means to use the left fringe
     width from the window's frame.

 -- Variable: right-fringe-width
     This variable, if non-`nil', specifies the width of the right
     fringe in pixels.  A value of `nil' means to use the right fringe
     width from the window's frame.

   Any buffer which does not specify values for these variables uses
the values specified by the `left-fringe' and `right-fringe' frame
parameters (*note Layout Parameters::).

   The above variables actually take effect via the function
`set-window-buffer' (*note Buffers and Windows::), which calls
`set-window-fringes' as a subroutine.  If you change one of these
variables, the fringe display is not updated in existing windows
showing the buffer, unless you call `set-window-buffer' again in each
affected window.  You can also use `set-window-fringes' to control the
fringe display in individual windows.

 -- Function: set-window-fringes window left &optional right
          outside-margins
     This function sets the fringe widths of window WINDOW.  If WINDOW
     is `nil', the selected window is used.

     The argument LEFT specifies the width in pixels of the left
     fringe, and likewise RIGHT for the right fringe.  A value of `nil'
     for either one stands for the default width.  If OUTSIDE-MARGINS
     is non-`nil', that specifies that fringes should appear outside of
     the display margins.

 -- Function: window-fringes &optional window
     This function returns information about the fringes of a window
     WINDOW.  If WINDOW is omitted or `nil', the selected window is
     used.  The value has the form `(LEFT-WIDTH RIGHT-WIDTH
     OUTSIDE-MARGINS)'.


File: elisp,  Node: Fringe Indicators,  Next: Fringe Cursors,  Prev: Fringe Size/Pos,  Up: Fringes

38.13.2 Fringe Indicators
-------------------------

"Fringe indicators" are tiny icons displayed in the window fringe to
indicate truncated or continued lines, buffer boundaries, etc.

 -- User Option: indicate-empty-lines
     When this is non-`nil', Emacs displays a special glyph in the
     fringe of each empty line at the end of the buffer, on graphical
     displays.  *Note Fringes::.  This variable is automatically
     buffer-local in every buffer.

 -- User Option: indicate-buffer-boundaries
     This buffer-local variable controls how the buffer boundaries and
     window scrolling are indicated in the window fringes.

     Emacs can indicate the buffer boundaries--that is, the first and
     last line in the buffer--with angle icons when they appear on the
     screen.  In addition, Emacs can display an up-arrow in the fringe
     to show that there is text above the screen, and a down-arrow to
     show there is text below the screen.

     There are three kinds of basic values:

    `nil'
          Don't display any of these fringe icons.

    `left'
          Display the angle icons and arrows in the left fringe.

    `right'
          Display the angle icons and arrows in the right fringe.

    any non-alist
          Display the angle icons in the left fringe and don't display
          the arrows.

     Otherwise the value should be an alist that specifies which fringe
     indicators to display and where.  Each element of the alist should
     have the form `(INDICATOR . POSITION)'.  Here, INDICATOR is one of
     `top', `bottom', `up', `down', and `t' (which covers all the icons
     not yet specified), while POSITION is one of `left', `right' and
     `nil'.

     For example, `((top . left) (t . right))' places the top angle
     bitmap in left fringe, and the bottom angle bitmap as well as both
     arrow bitmaps in right fringe.  To show the angle bitmaps in the
     left fringe, and no arrow bitmaps, use `((top .  left) (bottom .
     left))'.

 -- Variable: fringe-indicator-alist
     This buffer-local variable specifies the mapping from logical
     fringe indicators to the actual bitmaps displayed in the window
     fringes.  The value is an alist of elements `(INDICATOR .
     BITMAPS)', where INDICATOR specifies a logical indicator type and
     BITMAPS specifies the fringe bitmaps to use for that indicator.

     Each INDICATOR should be one of the following symbols:

    `truncation', `continuation'.
          Used for truncation and continuation lines.

    `up', `down', `top', `bottom', `top-bottom'
          Used when `indicate-buffer-boundaries' is non-`nil': `up' and
          `down' indicate a buffer boundary lying above or below the
          window edge; `top' and `bottom' indicate the topmost and
          bottommost buffer text line; and `top-bottom' indicates where
          there is just one line of text in the buffer.

    `empty-line'
          Used to indicate empty lines when `indicate-empty-lines' is
          non-`nil'.

    `overlay-arrow'
          Used for overlay arrows (*note Overlay Arrow::).

     Each BITMAPS value may be a list of symbols `(LEFT RIGHT [LEFT1
     RIGHT1])'.  The LEFT and RIGHT symbols specify the bitmaps shown
     in the left and/or right fringe, for the specific indicator.
     LEFT1 and RIGHT1 are specific to the `bottom' and `top-bottom'
     indicators, and are used to indicate that the last text line has
     no final newline.  Alternatively, BITMAPS may be a single symbol
     which is used in both left and right fringes.

     *Note Fringe Bitmaps::, for a list of standard bitmap symbols and
     how to define your own.  In addition, `nil' represents the empty
     bitmap (i.e. an indicator that is not shown).

     When `fringe-indicator-alist' has a buffer-local value, and there
     is no bitmap defined for a logical indicator, or the bitmap is
     `t', the corresponding value from the default value of
     `fringe-indicator-alist' is used.


File: elisp,  Node: Fringe Cursors,  Next: Fringe Bitmaps,  Prev: Fringe Indicators,  Up: Fringes

38.13.3 Fringe Cursors
----------------------

When a line is exactly as wide as the window, Emacs displays the cursor
in the right fringe instead of using two lines.  Different bitmaps are
used to represent the cursor in the fringe depending on the current
buffer's cursor type.

 -- User Option: overflow-newline-into-fringe
     If this is non-`nil', lines exactly as wide as the window (not
     counting the final newline character) are not continued.  Instead,
     when point is at the end of the line, the cursor appears in the
     right fringe.

 -- Variable: fringe-cursor-alist
     This variable specifies the mapping from logical cursor type to the
     actual fringe bitmaps displayed in the right fringe.  The value is
     an alist where each element has the form `(CURSOR-TYPE . BITMAP)',
     which means to use the fringe bitmap BITMAP to display cursors of
     type CURSOR-TYPE.

     Each CURSOR-TYPE should be one of `box', `hollow', `bar', `hbar',
     or `hollow-small'.  The first four have the same meanings as in
     the `cursor-type' frame parameter (*note Cursor Parameters::).
     The `hollow-small' type is used instead of `hollow' when the
     normal `hollow-rectangle' bitmap is too tall to fit on a specific
     display line.

     Each BITMAP should be a symbol specifying the fringe bitmap to be
     displayed for that logical cursor type.  *Note Fringe Bitmaps::.

     When `fringe-cursor-alist' has a buffer-local value, and there is
     no bitmap defined for a cursor type, the corresponding value from
     the default value of `fringes-indicator-alist' is used.


File: elisp,  Node: Fringe Bitmaps,  Next: Customizing Bitmaps,  Prev: Fringe Cursors,  Up: Fringes

38.13.4 Fringe Bitmaps
----------------------

The "fringe bitmaps" are the actual bitmaps which represent the logical
fringe indicators for truncated or continued lines, buffer boundaries,
overlay arrows, etc.  Each bitmap is represented by a symbol.  These
symbols are referred to by the variable `fringe-indicator-alist', which
maps fringe indicators to bitmaps (*note Fringe Indicators::), and the
variable `fringe-cursor-alist', which maps fringe cursors to bitmaps
(*note Fringe Cursors::).

   Lisp programs can also directly display a bitmap in the left or
right fringe, by using a `display' property for one of the characters
appearing in the line (*note Other Display Specs::).  Such a display
specification has the form

     (FRINGE BITMAP [FACE])

FRINGE is either the symbol `left-fringe' or `right-fringe'.  BITMAP is
a symbol identifying the bitmap to display.  The optional FACE names a
face whose foreground color is used to display the bitmap; this face is
automatically merged with the `fringe' face.

   Here is a list of the standard fringe bitmaps defined in Emacs, and
how they are currently used in Emacs (via `fringe-indicator-alist' and
`fringe-cursor-alist'):

`left-arrow', `right-arrow'
     Used to indicate truncated lines.

`left-curly-arrow', `right-curly-arrow'
     Used to indicate continued lines.

`right-triangle', `left-triangle'
     The former is used by overlay arrows.  The latter is unused.

`up-arrow', `down-arrow', `top-left-angle' `top-right-angle'
`bottom-left-angle', `bottom-right-angle'
`top-right-angle', `top-left-angle'
`left-bracket', `right-bracket', `top-right-angle', `top-left-angle'
     Used to indicate buffer boundaries.

`filled-rectangle', `hollow-rectangle'
`filled-square', `hollow-square'
`vertical-bar', `horizontal-bar'
     Used for different types of fringe cursors.

`empty-line', `question-mark'
     Unused.

The next subsection describes how to define your own fringe bitmaps.

 -- Function: fringe-bitmaps-at-pos &optional pos window
     This function returns the fringe bitmaps of the display line
     containing position POS in window WINDOW.  The return value has
     the form `(LEFT RIGHT OV)', where LEFT is the symbol for the
     fringe bitmap in the left fringe (or `nil' if no bitmap), RIGHT is
     similar for the right fringe, and OV is non-`nil' if there is an
     overlay arrow in the left fringe.

     The value is `nil' if POS is not visible in WINDOW.  If WINDOW is
     `nil', that stands for the selected window.  If POS is `nil', that
     stands for the value of point in WINDOW.


File: elisp,  Node: Customizing Bitmaps,  Next: Overlay Arrow,  Prev: Fringe Bitmaps,  Up: Fringes

38.13.5 Customizing Fringe Bitmaps
----------------------------------

 -- Function: define-fringe-bitmap bitmap bits &optional height width
          align
     This function defines the symbol BITMAP as a new fringe bitmap, or
     replaces an existing bitmap with that name.

     The argument BITS specifies the image to use.  It should be either
     a string or a vector of integers, where each element (an integer)
     corresponds to one row of the bitmap.  Each bit of an integer
     corresponds to one pixel of the bitmap, where the low bit
     corresponds to the rightmost pixel of the bitmap.

     The height is normally the length of BITS.  However, you can
     specify a different height with non-`nil' HEIGHT.  The width is
     normally 8, but you can specify a different width with non-`nil'
     WIDTH.  The width must be an integer between 1 and 16.

     The argument ALIGN specifies the positioning of the bitmap
     relative to the range of rows where it is used; the default is to
     center the bitmap.  The allowed values are `top', `center', or
     `bottom'.

     The ALIGN argument may also be a list `(ALIGN PERIODIC)' where
     ALIGN is interpreted as described above.  If PERIODIC is
     non-`nil', it specifies that the rows in `bits' should be repeated
     enough times to reach the specified height.

 -- Function: destroy-fringe-bitmap bitmap
     This function destroy the fringe bitmap identified by BITMAP.  If
     BITMAP identifies a standard fringe bitmap, it actually restores
     the standard definition of that bitmap, instead of eliminating it
     entirely.

 -- Function: set-fringe-bitmap-face bitmap &optional face
     This sets the face for the fringe bitmap BITMAP to FACE.  If FACE
     is `nil', it selects the `fringe' face.  The bitmap's face
     controls the color to draw it in.

     FACE is merged with the `fringe' face, so normally FACE should
     specify only the foreground color.


File: elisp,  Node: Overlay Arrow,  Prev: Customizing Bitmaps,  Up: Fringes

38.13.6 The Overlay Arrow
-------------------------

The "overlay arrow" is useful for directing the user's attention to a
particular line in a buffer.  For example, in the modes used for
interface to debuggers, the overlay arrow indicates the line of code
about to be executed.  This feature has nothing to do with "overlays"
(*note Overlays::).

 -- Variable: overlay-arrow-string
     This variable holds the string to display to call attention to a
     particular line, or `nil' if the arrow feature is not in use.  On
     a graphical display the contents of the string are ignored;
     instead a glyph is displayed in the fringe area to the left of the
     display area.

 -- Variable: overlay-arrow-position
     This variable holds a marker that indicates where to display the
     overlay arrow.  It should point at the beginning of a line.  On a
     non-graphical display the arrow text appears at the beginning of
     that line, overlaying any text that would otherwise appear.  Since
     the arrow is usually short, and the line usually begins with
     indentation, normally nothing significant is overwritten.

     The overlay-arrow string is displayed in any given buffer if the
     value of `overlay-arrow-position' in that buffer points into that
     buffer.  Thus, it is possible to display multiple overlay arrow
     strings by creating buffer-local bindings of
     `overlay-arrow-position'.  However, it is usually cleaner to use
     `overlay-arrow-variable-list' to achieve this result.

   You can do a similar job by creating an overlay with a
`before-string' property.  *Note Overlay Properties::.

   You can define multiple overlay arrows via the variable
`overlay-arrow-variable-list'.

 -- Variable: overlay-arrow-variable-list
     This variable's value is a list of variables, each of which
     specifies the position of an overlay arrow.  The variable
     `overlay-arrow-position' has its normal meaning because it is on
     this list.

   Each variable on this list can have properties
`overlay-arrow-string' and `overlay-arrow-bitmap' that specify an
overlay arrow string (for text terminals) or fringe bitmap (for
graphical terminals) to display at the corresponding overlay arrow
position.  If either property is not set, the default
`overlay-arrow-string' or `overlay-arrow' fringe indicator is used.


File: elisp,  Node: Scroll Bars,  Next: Display Property,  Prev: Fringes,  Up: Display

38.14 Scroll Bars
=================

Normally the frame parameter `vertical-scroll-bars' controls whether
the windows in the frame have vertical scroll bars, and whether they
are on the left or right.  The frame parameter `scroll-bar-width'
specifies how wide they are (`nil' meaning the default).  *Note Layout
Parameters::.

 -- Function: frame-current-scroll-bars &optional frame
     This function reports the scroll bar type settings for frame
     FRAME.  The value is a cons cell `(VERTICAL-TYPE .
     HORIZONTAL-TYPE)', where VERTICAL-TYPE is either `left', `right',
     or `nil' (which means no scroll bar.)  HORIZONTAL-TYPE is meant to
     specify the horizontal scroll bar type, but since they are not
     implemented, it is always `nil'.

   You can enable or disable scroll bars for a particular buffer, by
setting the variable `vertical-scroll-bar'.  This variable
automatically becomes buffer-local when set.  The possible values are
`left', `right', `t', which means to use the frame's default, and `nil'
for no scroll bar.

   You can also control this for individual windows.  Call the function
`set-window-scroll-bars' to specify what to do for a specific window:

 -- Function: set-window-scroll-bars window width &optional
          vertical-type horizontal-type
     This function sets the width and type of scroll bars for window
     WINDOW.

     WIDTH specifies the scroll bar width in pixels (`nil' means use
     the width specified for the frame).  VERTICAL-TYPE specifies
     whether to have a vertical scroll bar and, if so, where.  The
     possible values are `left', `right' and `nil', just like the
     values of the `vertical-scroll-bars' frame parameter.

     The argument HORIZONTAL-TYPE is meant to specify whether and where
     to have horizontal scroll bars, but since they are not
     implemented, it has no effect.  If WINDOW is `nil', the selected
     window is used.

 -- Function: window-scroll-bars &optional window
     Report the width and type of scroll bars specified for WINDOW.  If
     WINDOW is omitted or `nil', the selected window is used.  The
     value is a list of the form `(WIDTH COLS VERTICAL-TYPE
     HORIZONTAL-TYPE)'.  The value WIDTH is the value that was
     specified for the width (which may be `nil'); COLS is the number
     of columns that the scroll bar actually occupies.

     HORIZONTAL-TYPE is not actually meaningful.

   If you don't specify these values for a window with
`set-window-scroll-bars', the buffer-local variables `scroll-bar-mode'
and `scroll-bar-width' in the buffer being displayed control the
window's vertical scroll bars.  The function `set-window-buffer'
examines these variables.  If you change them in a buffer that is
already visible in a window, you can make the window take note of the
new values by calling `set-window-buffer' specifying the same buffer
that is already displayed.

 -- User Option: scroll-bar-mode
     This variable, always local in all buffers, controls whether and
     where to put scroll bars in windows displaying the buffer.  The
     possible values are `nil' for no scroll bar, `left' to put a
     scroll bar on the left, and `right' to put a scroll bar on the
     right.

 -- Function: window-current-scroll-bars &optional window
     This function reports the scroll bar type for window WINDOW.  If
     WINDOW is omitted or `nil', the selected window is used.  The
     value is a cons cell `(VERTICAL-TYPE . HORIZONTAL-TYPE)'.  Unlike
     `window-scroll-bars', this reports the scroll bar type actually
     used, once frame defaults and `scroll-bar-mode' are taken into
     account.

 -- Variable: scroll-bar-width
     This variable, always local in all buffers, specifies the width of
     the buffer's scroll bars, measured in pixels.  A value of `nil'
     means to use the value specified by the frame.


File: elisp,  Node: Display Property,  Next: Images,  Prev: Scroll Bars,  Up: Display

38.15 The `display' Property
============================

The `display' text property (or overlay property) is used to insert
images into text, and to control other aspects of how text displays.
The value of the `display' property should be a display specification,
or a list or vector containing several display specifications.  Display
specifications in the same `display' property value generally apply in
parallel to the text they cover.

   If several sources (overlays and/or a text property) specify values
for the `display' property, only one of the values takes effect,
following the rules of `get-char-property'.  *Note Examining
Properties::.

   The rest of this section describes several kinds of display
specifications and what they mean.

* Menu:

* Replacing Specs::      Display specs that replace the text.
* Specified Space::      Displaying one space with a specified width.
* Pixel Specification::  Specifying space width or height in pixels.
* Other Display Specs::     Displaying an image; adjusting the height,
                              spacing, and other properties of text.
* Display Margins::     Displaying text or images to the side of the main text.


File: elisp,  Node: Replacing Specs,  Next: Specified Space,  Up: Display Property

38.15.1 Display Specs That Replace The Text
-------------------------------------------

Some kinds of display specifications specify something to display
instead of the text that has the property.  These are called
"replacing" display specifications.  Emacs does not allow the user to
interactively move point into the middle of buffer text that is
replaced in this way.

   If a list of display specifications includes more than one replacing
display specification, the first overrides the rest.  Replacing display
specifications make most other display specifications irrelevant, since
those don't apply to the replacement.

   For replacing display specifications, "the text that has the
property" means all the consecutive characters that have the same Lisp
object as their `display' property; these characters are replaced as a
single unit.  If two characters have different Lisp objects as their
`display' properties (i.e. objects which are not `eq'), they are
handled separately.

   Here is an example which illustrates this point.  A string serves as
a replacing display specification, which replaces the text that has the
property with the specified string (*note Other Display Specs::).
Consider the following function:

     (defun foo ()
       (dotimes (i 5)
         (let ((string (concat "A"))
               (start (+ i i (point-min))))
           (put-text-property start (1+ start) 'display string)
           (put-text-property start (+ 2 start) 'display string))))

This function gives each of the first ten characters in the buffer a
`display' property which is a string `"A"', but they don't all get the
same string object.  The first two characters get the same string
object, so they are replaced with one `A'; the fact that the display
property was assigned in two separate calls to `put-text-property' is
irrelevant.  Similarly, the next two characters get a second string
(`concat' creates a new string object), so they are replaced with one
`A'; and so on.  Thus, the ten characters appear as five A's.


File: elisp,  Node: Specified Space,  Next: Pixel Specification,  Prev: Replacing Specs,  Up: Display Property

38.15.2 Specified Spaces
------------------------

To display a space of specified width and/or height, use a display
specification of the form `(space . PROPS)', where PROPS is a property
list (a list of alternating properties and values).  You can put this
property on one or more consecutive characters; a space of the
specified height and width is displayed in place of _all_ of those
characters.  These are the properties you can use in PROPS to specify
the weight of the space:

`:width WIDTH'
     If WIDTH is an integer or floating point number, it specifies that
     the space width should be WIDTH times the normal character width.
     WIDTH can also be a "pixel width" specification (*note Pixel
     Specification::).

`:relative-width FACTOR'
     Specifies that the width of the stretch should be computed from the
     first character in the group of consecutive characters that have
     the same `display' property.  The space width is the width of that
     character, multiplied by FACTOR.

`:align-to HPOS'
     Specifies that the space should be wide enough to reach HPOS.  If
     HPOS is a number, it is measured in units of the normal character
     width.  HPOS can also be a "pixel width" specification (*note
     Pixel Specification::).

   You should use one and only one of the above properties.  You can
also specify the height of the space, with these properties:

`:height HEIGHT'
     Specifies the height of the space.  If HEIGHT is an integer or
     floating point number, it specifies that the space height should
     be HEIGHT times the normal character height.  The HEIGHT may also
     be a "pixel height" specification (*note Pixel Specification::).

`:relative-height FACTOR'
     Specifies the height of the space, multiplying the ordinary height
     of the text having this display specification by FACTOR.

`:ascent ASCENT'
     If the value of ASCENT is a non-negative number no greater than
     100, it specifies that ASCENT percent of the height of the space
     should be considered as the ascent of the space--that is, the part
     above the baseline.  The ascent may also be specified in pixel
     units with a "pixel ascent" specification (*note Pixel
     Specification::).


   Don't use both `:height' and `:relative-height' together.

   The `:width' and `:align-to' properties are supported on non-graphic
terminals, but the other space properties in this section are not.

   Note that space properties are treated as paragraph separators for
the purposes of reordering bidirectional text for display.  *Note
Bidirectional Display::, for the details.


File: elisp,  Node: Pixel Specification,  Next: Other Display Specs,  Prev: Specified Space,  Up: Display Property

38.15.3 Pixel Specification for Spaces
--------------------------------------

The value of the `:width', `:align-to', `:height', and `:ascent'
properties can be a special kind of expression that is evaluated during
redisplay.  The result of the evaluation is used as an absolute number
of pixels.

   The following expressions are supported:

       EXPR ::= NUM | (NUM) | UNIT | ELEM | POS | IMAGE | FORM
       NUM  ::= INTEGER | FLOAT | SYMBOL
       UNIT ::= in | mm | cm | width | height
       ELEM ::= left-fringe | right-fringe | left-margin | right-margin
             |  scroll-bar | text
       POS  ::= left | center | right
       FORM ::= (NUM . EXPR) | (OP EXPR ...)
       OP   ::= + | -

   The form NUM specifies a fraction of the default frame font height
or width.  The form `(NUM)' specifies an absolute number of pixels.  If
NUM is a symbol, SYMBOL, its buffer-local variable binding is used.

   The `in', `mm', and `cm' units specify the number of pixels per
inch, millimeter, and centimeter, respectively.  The `width' and
`height' units correspond to the default width and height of the
current face.  An image specification `image' corresponds to the width
or height of the image.

   The elements `left-fringe', `right-fringe', `left-margin',
`right-margin', `scroll-bar', and `text' specify to the width of the
corresponding area of the window.

   The `left', `center', and `right' positions can be used with
`:align-to' to specify a position relative to the left edge, center, or
right edge of the text area.

   Any of the above window elements (except `text') can also be used
with `:align-to' to specify that the position is relative to the left
edge of the given area.  Once the base offset for a relative position
has been set (by the first occurrence of one of these symbols), further
occurrences of these symbols are interpreted as the width of the
specified area.  For example, to align to the center of the
left-margin, use

     :align-to (+ left-margin (0.5 . left-margin))

   If no specific base offset is set for alignment, it is always
relative to the left edge of the text area.  For example, `:align-to 0'
in a header-line aligns with the first text column in the text area.

   A value of the form `(NUM . EXPR)' stands for the product of the
values of NUM and EXPR.  For example, `(2 . in)' specifies a width of 2
inches, while `(0.5 .  IMAGE)' specifies half the width (or height) of
the specified image.

   The form `(+ EXPR ...)' adds up the value of the expressions.  The
form `(- EXPR ...)' negates or subtracts the value of the expressions.


File: elisp,  Node: Other Display Specs,  Next: Display Margins,  Prev: Pixel Specification,  Up: Display Property

38.15.4 Other Display Specifications
------------------------------------

Here are the other sorts of display specifications that you can use in
the `display' text property.

`STRING'
     Display STRING instead of the text that has this property.

     Recursive display specifications are not supported--STRING's
     `display' properties, if any, are not used.

`(image . IMAGE-PROPS)'
     This kind of display specification is an image descriptor (*note
     Images::).  When used as a display specification, it means to
     display the image instead of the text that has the display
     specification.

`(slice X Y WIDTH HEIGHT)'
     This specification together with `image' specifies a "slice" (a
     partial area) of the image to display.  The elements Y and X
     specify the top left corner of the slice, within the image; WIDTH
     and HEIGHT specify the width and height of the slice.  Integer
     values are numbers of pixels.  A floating point number in the
     range 0.0-1.0 stands for that fraction of the width or height of
     the entire image.

`((margin nil) STRING)'
     A display specification of this form means to display STRING
     instead of the text that has the display specification, at the same
     position as that text.  It is equivalent to using just STRING, but
     it is done as a special case of marginal display (*note Display
     Margins::).

`(left-fringe BITMAP [FACE])'
`(right-fringe BITMAP [FACE])'
     This display specification on any character of a line of text
     causes the specified BITMAP be displayed in the left or right
     fringes for that line, instead of the characters that have the
     display specification.  The optional FACE specifies the colors to
     be used for the bitmap.  *Note Fringe Bitmaps::, for the details.

`(space-width FACTOR)'
     This display specification affects all the space characters within
     the text that has the specification.  It displays all of these
     spaces FACTOR times as wide as normal.  The element FACTOR should
     be an integer or float.  Characters other than spaces are not
     affected at all; in particular, this has no effect on tab
     characters.

`(height HEIGHT)'
     This display specification makes the text taller or shorter.  Here
     are the possibilities for HEIGHT:

    `(+ N)'
          This means to use a font that is N steps larger.  A "step" is
          defined by the set of available fonts--specifically, those
          that match what was otherwise specified for this text, in all
          attributes except height.  Each size for which a suitable
          font is available counts as another step.  N should be an
          integer.

    `(- N)'
          This means to use a font that is N steps smaller.

    a number, FACTOR
          A number, FACTOR, means to use a font that is FACTOR times as
          tall as the default font.

    a symbol, FUNCTION
          A symbol is a function to compute the height.  It is called
          with the current height as argument, and should return the
          new height to use.

    anything else, FORM
          If the HEIGHT value doesn't fit the previous possibilities,
          it is a form.  Emacs evaluates it to get the new height, with
          the symbol `height' bound to the current specified font
          height.

`(raise FACTOR)'
     This kind of display specification raises or lowers the text it
     applies to, relative to the baseline of the line.

     FACTOR must be a number, which is interpreted as a multiple of the
     height of the affected text.  If it is positive, that means to
     display the characters raised.  If it is negative, that means to
     display them lower down.

     If the text also has a `height' display specification, that does
     not affect the amount of raising or lowering, which is based on the
     faces used for the text.

   You can make any display specification conditional.  To do that,
package it in another list of the form `(when CONDITION . SPEC)'.  Then
the specification SPEC applies only when CONDITION evaluates to a
non-`nil' value.  During the evaluation, `object' is bound to the
string or buffer having the conditional `display' property.  `position'
and `buffer-position' are bound to the position within `object' and the
buffer position where the `display' property was found, respectively.
Both positions can be different when `object' is a string.


File: elisp,  Node: Display Margins,  Prev: Other Display Specs,  Up: Display Property

38.15.5 Displaying in the Margins
---------------------------------

A buffer can have blank areas called "display margins" on the left and
on the right.  Ordinary text never appears in these areas, but you can
put things into the display margins using the `display' property.
There is currently no way to make text or images in the margin
mouse-sensitive.

   The way to display something in the margins is to specify it in a
margin display specification in the `display' property of some text.
This is a replacing display specification, meaning that the text you
put it on does not get displayed; the margin display appears, but that
text does not.

   A margin display specification looks like `((margin right-margin)
SPEC)' or `((margin left-margin) SPEC)'.  Here, SPEC is another display
specification that says what to display in the margin.  Typically it is
a string of text to display, or an image descriptor.

   To display something in the margin _in association with_ certain
buffer text, without altering or preventing the display of that text,
put a `before-string' property on the text and put the margin display
specification on the contents of the before-string.

   Before the display margins can display anything, you must give them
a nonzero width.  The usual way to do that is to set these variables:

 -- Variable: left-margin-width
     This variable specifies the width of the left margin.  It is
     buffer-local in all buffers.

 -- Variable: right-margin-width
     This variable specifies the width of the right margin.  It is
     buffer-local in all buffers.

   Setting these variables does not immediately affect the window.
These variables are checked when a new buffer is displayed in the
window.  Thus, you can make changes take effect by calling
`set-window-buffer'.

   You can also set the margin widths immediately.

 -- Function: set-window-margins window left &optional right
     This function specifies the margin widths for window WINDOW.  The
     argument LEFT controls the left margin and RIGHT controls the
     right margin (default `0').

 -- Function: window-margins &optional window
     This function returns the left and right margins of WINDOW as a
     cons cell of the form `(LEFT . RIGHT)'.  If WINDOW is `nil', the
     selected window is used.


File: elisp,  Node: Images,  Next: Buttons,  Prev: Display Property,  Up: Display

38.16 Images
============

To display an image in an Emacs buffer, you must first create an image
descriptor, then use it as a display specifier in the `display'
property of text that is displayed (*note Display Property::).

   Emacs is usually able to display images when it is run on a
graphical terminal.  Images cannot be displayed in a text terminal, on
certain graphical terminals that lack the support for this, or if Emacs
is compiled without image support.  You can use the function
`display-images-p' to determine if images can in principle be displayed
(*note Display Feature Testing::).

* Menu:

* Image Formats::       Supported image formats.
* Image Descriptors::   How to specify an image for use in `:display'.
* XBM Images::          Special features for XBM format.
* XPM Images::          Special features for XPM format.
* GIF Images::          Special features for GIF format.
* TIFF Images::         Special features for TIFF format.
* PostScript Images::   Special features for PostScript format.
* ImageMagick Images::  Special features available through ImageMagick.
* Other Image Types::   Various other formats are supported.
* Defining Images::     Convenient ways to define an image for later use.
* Showing Images::      Convenient ways to display an image once it is defined.
* Animated Images::     Some image formats can be animated.
* Image Cache::         Internal mechanisms of image display.


File: elisp,  Node: Image Formats,  Next: Image Descriptors,  Up: Images

38.16.1 Image Formats
---------------------

Emacs can display a number of different image formats.  Some of these
image formats are supported only if particular support libraries are
installed.  On some platforms, Emacs can load support libraries on
demand; if so, the variable `dynamic-library-alist' can be used to
modify the set of known names for these dynamic libraries.  *Note
Dynamic Libraries::.

   Supported image formats (and the required support libraries) include
PBM and XBM (which do not depend on support libraries and are always
available), XPM (`libXpm'), GIF (`libgif' or `libungif'), PostScript
(`gs'), JPEG (`libjpeg'), TIFF (`libtiff'), PNG (`libpng'), and SVG
(`librsvg').

   Each of these image formats is associated with an "image type
symbol".  The symbols for the above formats are, respectively, `pbm',
`xbm', `xpm', `gif', `postscript', `jpeg', `tiff', `png', and `svg'.

   Furthermore, if you build Emacs with ImageMagick (`libMagickWand')
support, Emacs can display any image format that ImageMagick can.
*Note ImageMagick Images::.  All images displayed via ImageMagick have
type symbol `imagemagick'.

 -- Variable: image-types
     This variable contains a list of type symbols for image formats
     which are potentially supported in the current configuration.

     "Potentially" means that Emacs knows about the image types, not
     necessarily that they can be used (for example, they could depend
     on unavailable dynamic libraries).  To know which image types are
     really available, use `image-type-available-p'.

 -- Function: image-type-available-p type
     This function returns non-`nil' if images of type TYPE can be
     loaded and displayed.  TYPE must be an image type symbol.

     For image types whose support libraries are statically linked, this
     function always returns `t'.  For image types whose support
     libraries are dynamically loaded, it returns `t' if the library
     could be loaded and `nil' otherwise.


File: elisp,  Node: Image Descriptors,  Next: XBM Images,  Prev: Image Formats,  Up: Images

38.16.2 Image Descriptors
-------------------------

An "image descriptor" is a list which specifies the underlying data for
an image, and how to display it.  It is typically used as the value of
a `display' overlay or text property (*note Other Display Specs::); but
*Note Showing Images::, for convenient helper functions to insert
images into buffers.

   Each image descriptor has the form `(image . PROPS)', where PROPS is
a property list of alternating keyword symbols and values, including at
least the pair `:type TYPE' which specifies the image type.

   The following is a list of properties that are meaningful for all
image types (there are also properties which are meaningful only for
certain image types, as documented in the following subsections):

`:type TYPE'
     The image type.  *Note Image Formats::.  Every image descriptor
     must include this property.

`:file FILE'
     This says to load the image from file FILE.  If FILE is not an
     absolute file name, it is expanded in `data-directory'.

`:data DATA'
     This specifies the raw image data.  Each image descriptor must have
     either `:data' or `:file', but not both.

     For most image types, the value of a `:data' property should be a
     string containing the image data.  Some image types do not support
     `:data'; for some others, `:data' alone is not enough, so you need
     to use other image properties along with `:data'.  See the
     following subsections for details.

`:margin MARGIN'
     This specifies how many pixels to add as an extra margin around the
     image.  The value, MARGIN, must be a non-negative number, or a
     pair `(X . Y)' of such numbers.  If it is a pair, X specifies how
     many pixels to add horizontally, and Y specifies how many pixels
     to add vertically.  If `:margin' is not specified, the default is
     zero.

`:ascent ASCENT'
     This specifies the amount of the image's height to use for its
     ascent--that is, the part above the baseline.  The value, ASCENT,
     must be a number in the range 0 to 100, or the symbol `center'.

     If ASCENT is a number, that percentage of the image's height is
     used for its ascent.

     If ASCENT is `center', the image is vertically centered around a
     centerline which would be the vertical centerline of text drawn at
     the position of the image, in the manner specified by the text
     properties and overlays that apply to the image.

     If this property is omitted, it defaults to 50.

`:relief RELIEF'
     This adds a shadow rectangle around the image.  The value, RELIEF,
     specifies the width of the shadow lines, in pixels.  If RELIEF is
     negative, shadows are drawn so that the image appears as a pressed
     button; otherwise, it appears as an unpressed button.

`:conversion ALGORITHM'
     This specifies a conversion algorithm that should be applied to the
     image before it is displayed; the value, ALGORITHM, specifies
     which algorithm.

    `laplace'
    `emboss'
          Specifies the Laplace edge detection algorithm, which blurs
          out small differences in color while highlighting larger
          differences.  People sometimes consider this useful for
          displaying the image for a "disabled" button.

    `(edge-detection :matrix MATRIX :color-adjust ADJUST)'
          Specifies a general edge-detection algorithm.  MATRIX must be
          either a nine-element list or a nine-element vector of
          numbers.  A pixel at position x/y in the transformed image is
          computed from original pixels around that position.  MATRIX
          specifies, for each pixel in the neighborhood of x/y, a
          factor with which that pixel will influence the transformed
          pixel; element 0 specifies the factor for the pixel at
          x-1/y-1, element 1 the factor for the pixel at x/y-1 etc., as
          shown below:
                 (x-1/y-1  x/y-1  x+1/y-1
                  x-1/y    x/y    x+1/y
                  x-1/y+1  x/y+1  x+1/y+1)

          The resulting pixel is computed from the color intensity of
          the color resulting from summing up the RGB values of
          surrounding pixels, multiplied by the specified factors, and
          dividing that sum by the sum of the factors' absolute values.

          Laplace edge-detection currently uses a matrix of
                 (1  0  0
                  0  0  0
                  0  0 -1)

          Emboss edge-detection uses a matrix of
                 ( 2 -1  0
                  -1  0  1
                   0  1 -2)

    `disabled'
          Specifies transforming the image so that it looks "disabled".

`:mask MASK'
     If MASK is `heuristic' or `(heuristic BG)', build a clipping mask
     for the image, so that the background of a frame is visible behind
     the image.  If BG is not specified, or if BG is `t', determine the
     background color of the image by looking at the four corners of
     the image, assuming the most frequently occurring color from the
     corners is the background color of the image.  Otherwise, BG must
     be a list `(RED GREEN BLUE)' specifying the color to assume for
     the background of the image.

     If MASK is `nil', remove a mask from the image, if it has one.
     Images in some formats include a mask which can be removed by
     specifying `:mask nil'.

`:pointer SHAPE'
     This specifies the pointer shape when the mouse pointer is over
     this image.  *Note Pointer Shape::, for available pointer shapes.

`:map MAP'
     This associates an image map of "hot spots" with this image.

     An image map is an alist where each element has the format `(AREA
     ID PLIST)'.  An AREA is specified as either a rectangle, a circle,
     or a polygon.

     A rectangle is a cons `(rect . ((X0 . Y0) . (X1 . Y1)))' which
     specifies the pixel coordinates of the upper left and bottom right
     corners of the rectangle area.

     A circle is a cons `(circle . ((X0 . Y0) . R))' which specifies
     the center and the radius of the circle; R may be a float or
     integer.

     A polygon is a cons `(poly . [X0 Y0 X1 Y1 ...])' where each pair
     in the vector describes one corner in the polygon.

     When the mouse pointer lies on a hot-spot area of an image, the
     PLIST of that hot-spot is consulted; if it contains a `help-echo'
     property, that defines a tool-tip for the hot-spot, and if it
     contains a `pointer' property, that defines the shape of the mouse
     cursor when it is on the hot-spot.  *Note Pointer Shape::, for
     available pointer shapes.

     When you click the mouse when the mouse pointer is over a
     hot-spot, an event is composed by combining the ID of the hot-spot
     with the mouse event; for instance, `[area4 mouse-1]' if the
     hot-spot's ID is `area4'.

 -- Function: image-mask-p spec &optional frame
     This function returns `t' if image SPEC has a mask bitmap.  FRAME
     is the frame on which the image will be displayed.  FRAME `nil' or
     omitted means to use the selected frame (*note Input Focus::).


File: elisp,  Node: XBM Images,  Next: XPM Images,  Prev: Image Descriptors,  Up: Images

38.16.3 XBM Images
------------------

To use XBM format, specify `xbm' as the image type.  This image format
doesn't require an external library, so images of this type are always
supported.

   Additional image properties supported for the `xbm' image type are:

`:foreground FOREGROUND'
     The value, FOREGROUND, should be a string specifying the image
     foreground color, or `nil' for the default color.  This color is
     used for each pixel in the XBM that is 1.  The default is the
     frame's foreground color.

`:background BACKGROUND'
     The value, BACKGROUND, should be a string specifying the image
     background color, or `nil' for the default color.  This color is
     used for each pixel in the XBM that is 0.  The default is the
     frame's background color.

   If you specify an XBM image using data within Emacs instead of an
external file, use the following three properties:

`:data DATA'
     The value, DATA, specifies the contents of the image.  There are
     three formats you can use for DATA:

        * A vector of strings or bool-vectors, each specifying one line
          of the image.  Do specify `:height' and `:width'.

        * A string containing the same byte sequence as an XBM file
          would contain.  You must not specify `:height' and `:width'
          in this case, because omitting them is what indicates the
          data has the format of an XBM file.  The file contents
          specify the height and width of the image.

        * A string or a bool-vector containing the bits of the image
          (plus perhaps some extra bits at the end that will not be
          used).  It should contain at least WIDTH * `height' bits.  In
          this case, you must specify `:height' and `:width', both to
          indicate that the string contains just the bits rather than a
          whole XBM file, and to specify the size of the image.

`:width WIDTH'
     The value, WIDTH, specifies the width of the image, in pixels.

`:height HEIGHT'
     The value, HEIGHT, specifies the height of the image, in pixels.


File: elisp,  Node: XPM Images,  Next: GIF Images,  Prev: XBM Images,  Up: Images

38.16.4 XPM Images
------------------

To use XPM format, specify `xpm' as the image type.  The additional
image property `:color-symbols' is also meaningful with the `xpm' image
type:

`:color-symbols SYMBOLS'
     The value, SYMBOLS, should be an alist whose elements have the
     form `(NAME . COLOR)'.  In each element, NAME is the name of a
     color as it appears in the image file, and COLOR specifies the
     actual color to use for displaying that name.


File: elisp,  Node: GIF Images,  Next: TIFF Images,  Prev: XPM Images,  Up: Images

38.16.5 GIF Images
------------------

For GIF images, specify image type `gif'.

`:index INDEX'
     You can use `:index' to specify image number INDEX from a GIF file
     that contains more than one image.  If the GIF file doesn't
     contain an image with the specified index, the image displays as a
     hollow box.  GIF files with more than one image can be animated,
     *note Animated Images::.


File: elisp,  Node: TIFF Images,  Next: PostScript Images,  Prev: GIF Images,  Up: Images

38.16.6 TIFF Images
-------------------

For TIFF images, specify image type `tiff'.

`:index INDEX'
     You can use `:index' to specify image number INDEX from a TIFF
     file that contains more than one image.  If the TIFF file doesn't
     contain an image with the specified index, the image displays as a
     hollow box.


File: elisp,  Node: PostScript Images,  Next: ImageMagick Images,  Prev: TIFF Images,  Up: Images

38.16.7 PostScript Images
-------------------------

To use PostScript for an image, specify image type `postscript'.  This
works only if you have Ghostscript installed.  You must always use
these three properties:

`:pt-width WIDTH'
     The value, WIDTH, specifies the width of the image measured in
     points (1/72 inch).  WIDTH must be an integer.

`:pt-height HEIGHT'
     The value, HEIGHT, specifies the height of the image in points
     (1/72 inch).  HEIGHT must be an integer.

`:bounding-box BOX'
     The value, BOX, must be a list or vector of four integers, which
     specifying the bounding box of the PostScript image, analogous to
     the `BoundingBox' comment found in PostScript files.

          %%BoundingBox: 22 171 567 738


File: elisp,  Node: ImageMagick Images,  Next: Other Image Types,  Prev: PostScript Images,  Up: Images

38.16.8 ImageMagick Images
--------------------------

If you build Emacs with ImageMagick support, you can use the
ImageMagick library to load many image formats.  The image type symbol
for images loaded via ImageMagick is `imagemagick', regardless of the
actual underlying image format.

 -- Function: imagemagick-types
     This function returns a list of image file extensions supported by
     the current ImageMagick installation.

   By default, Emacs does not use ImageMagick to display images in
Image mode, e.g. when visiting such files with `C-x C-f'.  This feature
is enabled by calling `imagemagick-register-types'.

 -- Function: imagemagick-register-types
     This function enables using Image mode to visit image files
     supported by ImageMagick.  *Note File Conveniences: (emacs)File
     Conveniences.  It also causes `create-image' and other helper
     functions to associate such file names with the `imagemagick'
     image type (*note Defining Images::).

     All image file extensions supported by ImageMagick are registered,
     except those specified in `imagemagick-types-inhibit'.  If Emacs
     was not compiled with ImageMagick support, this function does
     nothing.

 -- User Option: imagemagick-types-inhibit
     This variable specifies a list of image types that should _not_ be
     registered by `imagemagick-register-types'.  Each entry in this
     list should be one of the symbols returned by `imagemagick-types'.
     The default value lists several file types that are considered
     "images" by ImageMagick, but which should not be considered as
     images by Emacs, including C files and HTML files.

   Images loaded with ImageMagick support the following additional
image descriptor properties:

`:width, :height'
     The `:width' and `:height' keywords are used for scaling the
     image.  If only one of them is specified, the other one will be
     calculated so as to preserve the aspect ratio.  If both are
     specified, aspect ratio may not be preserved.

`:rotation'
     Specifies a rotation angle in degrees.

`:index'
     This has the same meaning as it does for GIF images (*note GIF
     Images::), i.e. it specifies which image to view inside an image
     bundle file format such as DJVM.  You can use the `image-metadata'
     function to retrieve the total number of images in an image bundle.


File: elisp,  Node: Other Image Types,  Next: Defining Images,  Prev: ImageMagick Images,  Up: Images

38.16.9 Other Image Types
-------------------------

For PBM images, specify image type `pbm'.  Color, gray-scale and
monochromatic images are supported.   For mono PBM images, two
additional image properties are supported.

`:foreground FOREGROUND'
     The value, FOREGROUND, should be a string specifying the image
     foreground color, or `nil' for the default color.  This color is
     used for each pixel in the PBM that is 1.  The default is the
     frame's foreground color.

`:background BACKGROUND'
     The value, BACKGROUND, should be a string specifying the image
     background color, or `nil' for the default color.  This color is
     used for each pixel in the PBM that is 0.  The default is the
     frame's background color.

   For JPEG images, specify image type `jpeg'.

   For TIFF images, specify image type `tiff'.

   For PNG images, specify image type `png'.

   For SVG images, specify image type `svg'.


File: elisp,  Node: Defining Images,  Next: Showing Images,  Prev: Other Image Types,  Up: Images

38.16.10 Defining Images
------------------------

The functions `create-image', `defimage' and `find-image' provide
convenient ways to create image descriptors.

 -- Function: create-image file-or-data &optional type data-p &rest
          props
     This function creates and returns an image descriptor which uses
     the data in FILE-OR-DATA.  FILE-OR-DATA can be a file name or a
     string containing the image data; DATA-P should be `nil' for the
     former case, non-`nil' for the latter case.

     The optional argument TYPE is a symbol specifying the image type.
     If TYPE is omitted or `nil', `create-image' tries to determine the
     image type from the file's first few bytes, or else from the
     file's name.

     The remaining arguments, PROPS, specify additional image
     properties--for example,

          (create-image "foo.xpm" 'xpm nil :heuristic-mask t)

     The function returns `nil' if images of this type are not
     supported.  Otherwise it returns an image descriptor.

 -- Macro: defimage symbol specs &optional doc
     This macro defines SYMBOL as an image name.  The arguments SPECS
     is a list which specifies how to display the image.  The third
     argument, DOC, is an optional documentation string.

     Each argument in SPECS has the form of a property list, and each
     one should specify at least the `:type' property and either the
     `:file' or the `:data' property.  The value of `:type' should be a
     symbol specifying the image type, the value of `:file' is the file
     to load the image from, and the value of `:data' is a string
     containing the actual image data.  Here is an example:

          (defimage test-image
            ((:type xpm :file "~/test1.xpm")
             (:type xbm :file "~/test1.xbm")))

     `defimage' tests each argument, one by one, to see if it is
     usable--that is, if the type is supported and the file exists.  The
     first usable argument is used to make an image descriptor which is
     stored in SYMBOL.

     If none of the alternatives will work, then SYMBOL is defined as
     `nil'.

 -- Function: find-image specs
     This function provides a convenient way to find an image
     satisfying one of a list of image specifications SPECS.

     Each specification in SPECS is a property list with contents
     depending on image type.  All specifications must at least contain
     the properties `:type TYPE' and either `:file FILE' or
     `:data DATA', where TYPE is a symbol specifying the image type,
     e.g. `xbm', FILE is the file to load the image from, and DATA is a
     string containing the actual image data.  The first specification
     in the list whose TYPE is supported, and FILE exists, is used to
     construct the image specification to be returned.  If no
     specification is satisfied, `nil' is returned.

     The image is looked for in `image-load-path'.

 -- Variable: image-load-path
     This variable's value is a list of locations in which to search for
     image files.  If an element is a string or a variable symbol whose
     value is a string, the string is taken to be the name of a
     directory to search.  If an element is a variable symbol whose
     value is a list, that is taken to be a list of directory names to
     search.

     The default is to search in the `images' subdirectory of the
     directory specified by `data-directory', then the directory
     specified by `data-directory', and finally in the directories in
     `load-path'.  Subdirectories are not automatically included in the
     search, so if you put an image file in a subdirectory, you have to
     supply the subdirectory name explicitly.  For example, to find the
     image `images/foo/bar.xpm' within `data-directory', you should
     specify the image as follows:

          (defimage foo-image '((:type xpm :file "foo/bar.xpm")))

 -- Function: image-load-path-for-library library image &optional path
          no-error
     This function returns a suitable search path for images used by the
     Lisp package LIBRARY.

     The function searches for IMAGE first using `image-load-path',
     excluding ``data-directory'/images', and then in `load-path',
     followed by a path suitable for LIBRARY, which includes
     `../../etc/images' and `../etc/images' relative to the library
     file itself, and finally in ``data-directory'/images'.

     Then this function returns a list of directories which contains
     first the directory in which IMAGE was found, followed by the
     value of `load-path'.  If PATH is given, it is used instead of
     `load-path'.

     If NO-ERROR is non-`nil' and a suitable path can't be found, don't
     signal an error.  Instead, return a list of directories as before,
     except that `nil' appears in place of the image directory.

     Here is an example of using `image-load-path-for-library':

          (defvar image-load-path) ; shush compiler
          (let* ((load-path (image-load-path-for-library
                              "mh-e" "mh-logo.xpm"))
                 (image-load-path (cons (car load-path)
                                        image-load-path)))
            (mh-tool-bar-folder-buttons-init))


File: elisp,  Node: Showing Images,  Next: Animated Images,  Prev: Defining Images,  Up: Images

38.16.11 Showing Images
-----------------------

You can use an image descriptor by setting up the `display' property
yourself, but it is easier to use the functions in this section.

 -- Function: insert-image image &optional string area slice
     This function inserts IMAGE in the current buffer at point.  The
     value IMAGE should be an image descriptor; it could be a value
     returned by `create-image', or the value of a symbol defined with
     `defimage'.  The argument STRING specifies the text to put in the
     buffer to hold the image.  If it is omitted or `nil',
     `insert-image' uses `" "' by default.

     The argument AREA specifies whether to put the image in a margin.
     If it is `left-margin', the image appears in the left margin;
     `right-margin' specifies the right margin.  If AREA is `nil' or
     omitted, the image is displayed at point within the buffer's text.

     The argument SLICE specifies a slice of the image to insert.  If
     SLICE is `nil' or omitted the whole image is inserted.  Otherwise,
     SLICE is a list `(X Y WIDTH HEIGHT)' which specifies the X and Y
     positions and WIDTH and HEIGHT of the image area to insert.
     Integer values are in units of pixels.  A floating point number in
     the range 0.0-1.0 stands for that fraction of the width or height
     of the entire image.

     Internally, this function inserts STRING in the buffer, and gives
     it a `display' property which specifies IMAGE.  *Note Display
     Property::.

 -- Function: insert-sliced-image image &optional string area rows cols
     This function inserts IMAGE in the current buffer at point, like
     `insert-image', but splits the image into ROWSxCOLS equally sized
     slices.

     If an image is inserted "sliced", Emacs displays each slice as a
     separate image, and allow more intuitive scrolling up/down,
     instead of jumping up/down the entire image when paging through a
     buffer that displays (large) images.

 -- Function: put-image image pos &optional string area
     This function puts image IMAGE in front of POS in the current
     buffer.  The argument POS should be an integer or a marker.  It
     specifies the buffer position where the image should appear.  The
     argument STRING specifies the text that should hold the image as
     an alternative to the default.

     The argument IMAGE must be an image descriptor, perhaps returned
     by `create-image' or stored by `defimage'.

     The argument AREA specifies whether to put the image in a margin.
     If it is `left-margin', the image appears in the left margin;
     `right-margin' specifies the right margin.  If AREA is `nil' or
     omitted, the image is displayed at point within the buffer's text.

     Internally, this function creates an overlay, and gives it a
     `before-string' property containing text that has a `display'
     property whose value is the image.  (Whew!)

 -- Function: remove-images start end &optional buffer
     This function removes images in BUFFER between positions START and
     END.  If BUFFER is omitted or `nil', images are removed from the
     current buffer.

     This removes only images that were put into BUFFER the way
     `put-image' does it, not images that were inserted with
     `insert-image' or in other ways.

 -- Function: image-size spec &optional pixels frame
     This function returns the size of an image as a pair
     `(WIDTH . HEIGHT)'.  SPEC is an image specification.  PIXELS
     non-`nil' means return sizes measured in pixels, otherwise return
     sizes measured in canonical character units (fractions of the
     width/height of the frame's default font).  FRAME is the frame on
     which the image will be displayed.  FRAME null or omitted means
     use the selected frame (*note Input Focus::).

 -- Variable: max-image-size
     This variable is used to define the maximum size of image that
     Emacs will load.  Emacs will refuse to load (and display) any
     image that is larger than this limit.

     If the value is an integer, it directly specifies the maximum
     image height and width, measured in pixels.  If it is a floating
     point number, it specifies the maximum image height and width as a
     ratio to the frame height and width.  If the value is non-numeric,
     there is no explicit limit on the size of images.

     The purpose of this variable is to prevent unreasonably large
     images from accidentally being loaded into Emacs.  It only takes
     effect the first time an image is loaded.  Once an image is placed
     in the image cache, it can always be displayed, even if the value
     of MAX-IMAGE-SIZE is subsequently changed (*note Image Cache::).


File: elisp,  Node: Animated Images,  Next: Image Cache,  Prev: Showing Images,  Up: Images

38.16.12 Animated Images
------------------------

Some image files can contain more than one image.  This can be used to
create animation.  Currently, Emacs only supports animated GIF files.
The following functions related to animated images are available.

 -- Function: image-animated-p image
     This function returns non-`nil' if IMAGE can be animated.  The
     actual return value is a cons `(NIMAGES . DELAY)', where NIMAGES
     is the number of frames and DELAY is the delay in seconds between
     them.

 -- Function: image-animate image &optional index limit
     This function animates IMAGE.  The optional integer INDEX
     specifies the frame from which to start (default 0).  The optional
     argument LIMIT controls the length of the animation.  If omitted
     or `nil', the image animates once only; if `t' it loops forever;
     if a number animation stops after that many seconds.

Animation operates by means of a timer.  Note that Emacs imposes a
minimum frame delay of 0.01 seconds.

 -- Function: image-animate-timer image
     This function returns the timer responsible for animating IMAGE,
     if there is one.


File: elisp,  Node: Image Cache,  Prev: Animated Images,  Up: Images

38.16.13 Image Cache
--------------------

Emacs caches images so that it can display them again more efficiently.
When Emacs displays an image, it searches the image cache for an
existing image specification `equal' to the desired specification.  If
a match is found, the image is displayed from the cache.  Otherwise,
Emacs loads the image normally.

 -- Function: image-flush spec &optional frame
     This function removes the image with specification SPEC from the
     image cache of frame FRAME.  Image specifications are compared
     using `equal'.  If FRAME is `nil', it defaults to the selected
     frame.  If FRAME is `t', the image is flushed on all existing
     frames.

     In Emacs's current implementation, each graphical terminal
     possesses an image cache, which is shared by all the frames on
     that terminal (*note Multiple Terminals::).  Thus, refreshing an
     image in one frame also refreshes it in all other frames on the
     same terminal.

   One use for `image-flush' is to tell Emacs about a change in an
image file.  If an image specification contains a `:file' property, the
image is cached based on the file's contents when the image is first
displayed.  Even if the file subsequently changes, Emacs continues
displaying the old version of the image.  Calling `image-flush' flushes
the image from the cache, forcing Emacs to re-read the file the next
time it needs to display that image.

   Another use for `image-flush' is for memory conservation.  If your
Lisp program creates a large number of temporary images over a period
much shorter than `image-cache-eviction-delay' (see below), you can opt
to flush unused images yourself, instead of waiting for Emacs to do it
automatically.

 -- Function: clear-image-cache &optional filter
     This function clears an image cache, removing all the images
     stored in it.  If FILTER is omitted or `nil', it clears the cache
     for the selected frame.  If FILTER is a frame, it clears the cache
     for that frame.  If FILTER is `t', all image caches are cleared.
     Otherwise, FILTER is taken to be a file name, and all images
     associated with that file name are removed from all image caches.

   If an image in the image cache has not been displayed for a specified
period of time, Emacs removes it from the cache and frees the
associated memory.

 -- Variable: image-cache-eviction-delay
     This variable specifies the number of seconds an image can remain
     in the cache without being displayed.  When an image is not
     displayed for this length of time, Emacs removes it from the image
     cache.

     Under some circumstances, if the number of images in the cache
     grows too large, the actual eviction delay may be shorter than
     this.

     If the value is `nil', Emacs does not remove images from the cache
     except when you explicitly clear it.  This mode can be useful for
     debugging.


File: elisp,  Node: Buttons,  Next: Abstract Display,  Prev: Images,  Up: Display

38.17 Buttons
=============

The Button package defines functions for inserting and manipulating
"buttons" that can be activated with the mouse or via keyboard
commands.  These buttons are typically used for various kinds of
hyperlinks.

   A button is essentially a set of text or overlay properties,
attached to a stretch of text in a buffer.  These properties are called
"button properties".  One of these properties, the "action property",
specifies a function which is called when the user invokes the button
using the keyboard or the mouse.  The action function may examine the
button and use its other properties as desired.

   In some ways, the Button package duplicates the functionality in the
Widget package.  *Note Introduction: (widget)Top.  The advantage of the
Button package is that it is faster, smaller, and simpler to program.
From the point of view of the user, the interfaces produced by the two
packages are very similar.

* Menu:

* Button Properties::      Button properties with special meanings.
* Button Types::           Defining common properties for classes of buttons.
* Making Buttons::         Adding buttons to Emacs buffers.
* Manipulating Buttons::   Getting and setting properties of buttons.
* Button Buffer Commands:: Buffer-wide commands and bindings for buttons.


File: elisp,  Node: Button Properties,  Next: Button Types,  Up: Buttons

38.17.1 Button Properties
-------------------------

Each button has an associated list of properties defining its
appearance and behavior, and other arbitrary properties may be used for
application specific purposes.  The following properties have special
meaning to the Button package:

`action'
     The function to call when the user invokes the button, which is
     passed the single argument BUTTON.  By default this is `ignore',
     which does nothing.

`mouse-action'
     This is similar to `action', and when present, will be used
     instead of `action' for button invocations resulting from
     mouse-clicks (instead of the user hitting <RET>).  If not present,
     mouse-clicks use `action' instead.

`face'
     This is an Emacs face controlling how buttons of this type are
     displayed; by default this is the `button' face.

`mouse-face'
     This is an additional face which controls appearance during
     mouse-overs (merged with the usual button face); by default this is
     the usual Emacs `highlight' face.

`keymap'
     The button's keymap, defining bindings active within the button
     region.  By default this is the usual button region keymap, stored
     in the variable `button-map', which defines <RET> and <mouse-2> to
     invoke the button.

`type'
     The button type.  *Note Button Types::.

`help-echo'
     A string displayed by the Emacs tool-tip help system; by default,
     `"mouse-2, RET: Push this button"'.

`follow-link'
     The follow-link property, defining how a <Mouse-1> click behaves
     on this button, *Note Clickable Text::.

`button'
     All buttons have a non-`nil' `button' property, which may be useful
     in finding regions of text that comprise buttons (which is what the
     standard button functions do).

   There are other properties defined for the regions of text in a
button, but these are not generally interesting for typical uses.


File: elisp,  Node: Button Types,  Next: Making Buttons,  Prev: Button Properties,  Up: Buttons

38.17.2 Button Types
--------------------

Every button has a "button type", which defines default values for the
button's properties.  Button types are arranged in a hierarchy, with
specialized types inheriting from more general types, so that it's easy
to define special-purpose types of buttons for specific tasks.

 -- Function: define-button-type name &rest properties
     Define a `button type' called NAME (a symbol).  The remaining
     arguments form a sequence of PROPERTY VALUE pairs, specifying
     default property values for buttons with this type (a button's
     type may be set by giving it a `type' property when creating the
     button, using the `:type' keyword argument).

     In addition, the keyword argument `:supertype' may be used to
     specify a button-type from which NAME inherits its default
     property values.  Note that this inheritance happens only when
     NAME is defined; subsequent changes to a supertype are not
     reflected in its subtypes.

   Using `define-button-type' to define default properties for buttons
is not necessary--buttons without any specified type use the built-in
button-type `button'--but it is encouraged, since doing so usually
makes the resulting code clearer and more efficient.


File: elisp,  Node: Making Buttons,  Next: Manipulating Buttons,  Prev: Button Types,  Up: Buttons

38.17.3 Making Buttons
----------------------

Buttons are associated with a region of text, using an overlay or text
properties to hold button-specific information, all of which are
initialized from the button's type (which defaults to the built-in
button type `button').  Like all Emacs text, the appearance of the
button is governed by the `face' property; by default (via the `face'
property inherited from the `button' button-type) this is a simple
underline, like a typical web-page link.

   For convenience, there are two sorts of button-creation functions,
those that add button properties to an existing region of a buffer,
called `make-...button', and those that also insert the button text,
called `insert-...button'.

   The button-creation functions all take the `&rest' argument
PROPERTIES, which should be a sequence of PROPERTY VALUE pairs,
specifying properties to add to the button; see *note Button
Properties::.  In addition, the keyword argument `:type' may be used to
specify a button-type from which to inherit other properties; see *note
Button Types::.  Any properties not explicitly specified during
creation will be inherited from the button's type (if the type defines
such a property).

   The following functions add a button using an overlay (*note
Overlays::) to hold the button properties:

 -- Function: make-button beg end &rest properties
     This makes a button from BEG to END in the current buffer, and
     returns it.

 -- Function: insert-button label &rest properties
     This insert a button with the label LABEL at point, and returns it.

   The following functions are similar, but using text properties
(*note Text Properties::) to hold the button properties.  Such buttons
do not add markers to the buffer, so editing in the buffer does not
slow down if there is an extremely large numbers of buttons.  However,
if there is an existing face text property on the text (e.g. a face
assigned by Font Lock mode), the button face may not be visible.  Both
of these functions return the starting position of the new button.

 -- Function: make-text-button beg end &rest properties
     This makes a button from BEG to END in the current buffer, using
     text properties.

 -- Function: insert-text-button label &rest properties
     This inserts a button with the label LABEL at point, using text
     properties.


File: elisp,  Node: Manipulating Buttons,  Next: Button Buffer Commands,  Prev: Making Buttons,  Up: Buttons

38.17.4 Manipulating Buttons
----------------------------

These are functions for getting and setting properties of buttons.
Often these are used by a button's invocation function to determine
what to do.

   Where a BUTTON parameter is specified, it means an object referring
to a specific button, either an overlay (for overlay buttons), or a
buffer-position or marker (for text property buttons).  Such an object
is passed as the first argument to a button's invocation function when
it is invoked.

 -- Function: button-start button
     Return the position at which BUTTON starts.

 -- Function: button-end button
     Return the position at which BUTTON ends.

 -- Function: button-get button prop
     Get the property of button BUTTON named PROP.

 -- Function: button-put button prop val
     Set BUTTON's PROP property to VAL.

 -- Function: button-activate button &optional use-mouse-action
     Call BUTTON's `action' property (i.e., invoke it).  If
     USE-MOUSE-ACTION is non-`nil', try to invoke the button's
     `mouse-action' property instead of `action'; if the button has no
     `mouse-action' property, use `action' as normal.

 -- Function: button-label button
     Return BUTTON's text label.

 -- Function: button-type button
     Return BUTTON's button-type.

 -- Function: button-has-type-p button type
     Return `t' if BUTTON has button-type TYPE, or one of TYPE's
     subtypes.

 -- Function: button-at pos
     Return the button at position POS in the current buffer, or `nil'.
     If the button at POS is a text property button, the return value
     is a marker pointing to POS.

 -- Function: button-type-put type prop val
     Set the button-type TYPE's PROP property to VAL.

 -- Function: button-type-get type prop
     Get the property of button-type TYPE named PROP.

 -- Function: button-type-subtype-p type supertype
     Return `t' if button-type TYPE is a subtype of SUPERTYPE.


File: elisp,  Node: Button Buffer Commands,  Prev: Manipulating Buttons,  Up: Buttons

38.17.5 Button Buffer Commands
------------------------------

These are commands and functions for locating and operating on buttons
in an Emacs buffer.

   `push-button' is the command that a user uses to actually `push' a
button, and is bound by default in the button itself to <RET> and to
<mouse-2> using a local keymap in the button's overlay or text
properties.  Commands that are useful outside the buttons itself, such
as `forward-button' and `backward-button' are additionally available in
the keymap stored in `button-buffer-map'; a mode which uses buttons may
want to use `button-buffer-map' as a parent keymap for its keymap.

   If the button has a non-`nil' `follow-link' property, and
MOUSE-1-CLICK-FOLLOWS-LINK is set, a quick <Mouse-1> click will also
activate the `push-button' command.  *Note Clickable Text::.

 -- Command: push-button &optional pos use-mouse-action
     Perform the action specified by a button at location POS.  POS may
     be either a buffer position or a mouse-event.  If USE-MOUSE-ACTION
     is non-`nil', or POS is a mouse-event (*note Mouse Events::), try
     to invoke the button's `mouse-action' property instead of
     `action'; if the button has no `mouse-action' property, use
     `action' as normal.  POS defaults to point, except when
     `push-button' is invoked interactively as the result of a
     mouse-event, in which case, the mouse event's position is used.
     If there's no button at POS, do nothing and return `nil',
     otherwise return `t'.

 -- Command: forward-button n &optional wrap display-message
     Move to the Nth next button, or Nth previous button if N is
     negative.  If N is zero, move to the start of any button at point.
     If WRAP is non-`nil', moving past either end of the buffer
     continues from the other end.  If DISPLAY-MESSAGE is non-`nil',
     the button's help-echo string is displayed.  Any button with a
     non-`nil' `skip' property is skipped over.  Returns the button
     found.

 -- Command: backward-button n &optional wrap display-message
     Move to the Nth previous button, or Nth next button if N is
     negative.  If N is zero, move to the start of any button at point.
     If WRAP is non-`nil', moving past either end of the buffer
     continues from the other end.  If DISPLAY-MESSAGE is non-`nil',
     the button's help-echo string is displayed.  Any button with a
     non-`nil' `skip' property is skipped over.  Returns the button
     found.

 -- Function: next-button pos &optional count-current
 -- Function: previous-button pos &optional count-current
     Return the next button after (for `next-button' or before (for
     `previous-button') position POS in the current buffer.  If
     COUNT-CURRENT is non-`nil', count any button at POS in the search,
     instead of starting at the next button.


File: elisp,  Node: Abstract Display,  Next: Blinking,  Prev: Buttons,  Up: Display

38.18 Abstract Display
======================

The Ewoc package constructs buffer text that represents a structure of
Lisp objects, and updates the text to follow changes in that structure.
This is like the "view" component in the "model/view/controller" design
paradigm.

   An "ewoc" is a structure that organizes information required to
construct buffer text that represents certain Lisp data.  The buffer
text of the ewoc has three parts, in order: first, fixed "header" text;
next, textual descriptions of a series of data elements (Lisp objects
that you specify); and last, fixed "footer" text.  Specifically, an
ewoc contains information on:

   * The buffer which its text is generated in.

   * The text's start position in the buffer.

   * The header and footer strings.

   * A doubly-linked chain of "nodes", each of which contains:

        * A "data element", a single Lisp object.

        * Links to the preceding and following nodes in the chain.

   * A "pretty-printer" function which is responsible for inserting the
     textual representation of a data element value into the current
     buffer.

   Typically, you define an ewoc with `ewoc-create', and then pass the
resulting ewoc structure to other functions in the Ewoc package to
build nodes within it, and display it in the buffer.  Once it is
displayed in the buffer, other functions determine the correspondence
between buffer positions and nodes, move point from one node's textual
representation to another, and so forth.  *Note Abstract Display
Functions::.

   A node "encapsulates" a data element much the way a variable holds a
value.  Normally, encapsulation occurs as a part of adding a node to
the ewoc.  You can retrieve the data element value and place a new
value in its place, like so:

     (ewoc-data NODE)
     => value

     (ewoc-set-data NODE NEW-VALUE)
     => NEW-VALUE

You can also use, as the data element value, a Lisp object (list or
vector) that is a container for the "real" value, or an index into some
other structure.  The example (*note Abstract Display Example::) uses
the latter approach.

   When the data changes, you will want to update the text in the
buffer.  You can update all nodes by calling `ewoc-refresh', or just
specific nodes using `ewoc-invalidate', or all nodes satisfying a
predicate using `ewoc-map'.  Alternatively, you can delete invalid
nodes using `ewoc-delete' or `ewoc-filter', and add new nodes in their
place.  Deleting a node from an ewoc deletes its associated textual
description from buffer, as well.

* Menu:

* Abstract Display Functions::  Functions in the Ewoc package.
* Abstract Display Example::    Example of using Ewoc.


File: elisp,  Node: Abstract Display Functions,  Next: Abstract Display Example,  Up: Abstract Display

38.18.1 Abstract Display Functions
----------------------------------

In this subsection, EWOC and NODE stand for the structures described
above (*note Abstract Display::), while DATA stands for an arbitrary
Lisp object used as a data element.

 -- Function: ewoc-create pretty-printer &optional header footer nosep
     This constructs and returns a new ewoc, with no nodes (and thus no
     data elements).  PRETTY-PRINTER should be a function that takes one
     argument, a data element of the sort you plan to use in this ewoc,
     and inserts its textual description at point using `insert' (and
     never `insert-before-markers', because that would interfere with
     the Ewoc package's internal mechanisms).

     Normally, a newline is automatically inserted after the header,
     the footer and every node's textual description.  If NOSEP is
     non-`nil', no newline is inserted.  This may be useful for
     displaying an entire ewoc on a single line, for example, or for
     making nodes "invisible" by arranging for PRETTY-PRINTER to do
     nothing for those nodes.

     An ewoc maintains its text in the buffer that is current when you
     create it, so switch to the intended buffer before calling
     `ewoc-create'.

 -- Function: ewoc-buffer ewoc
     This returns the buffer where EWOC maintains its text.

 -- Function: ewoc-get-hf ewoc
     This returns a cons cell `(HEADER . FOOTER)' made from EWOC's
     header and footer.

 -- Function: ewoc-set-hf ewoc header footer
     This sets the header and footer of EWOC to the strings HEADER and
     FOOTER, respectively.

 -- Function: ewoc-enter-first ewoc data
 -- Function: ewoc-enter-last ewoc data
     These add a new node encapsulating DATA, putting it, respectively,
     at the beginning or end of EWOC's chain of nodes.

 -- Function: ewoc-enter-before ewoc node data
 -- Function: ewoc-enter-after ewoc node data
     These add a new node encapsulating DATA, adding it to EWOC before
     or after NODE, respectively.

 -- Function: ewoc-prev ewoc node
 -- Function: ewoc-next ewoc node
     These return, respectively, the previous node and the next node of
     NODE in EWOC.

 -- Function: ewoc-nth ewoc n
     This returns the node in EWOC found at zero-based index N.  A
     negative N means count from the end.  `ewoc-nth' returns `nil' if
     N is out of range.

 -- Function: ewoc-data node
     This extracts the data encapsulated by NODE and returns it.

 -- Function: ewoc-set-data node data
     This sets the data encapsulated by NODE to DATA.

 -- Function: ewoc-locate ewoc &optional pos guess
     This determines the node in EWOC which contains point (or POS if
     specified), and returns that node.  If EWOC has no nodes, it
     returns `nil'.  If POS is before the first node, it returns the
     first node; if POS is after the last node, it returns the last
     node.  The optional third arg GUESS should be a node that is
     likely to be near POS; this doesn't alter the result, but makes
     the function run faster.

 -- Function: ewoc-location node
     This returns the start position of NODE.

 -- Function: ewoc-goto-prev ewoc arg
 -- Function: ewoc-goto-next ewoc arg
     These move point to the previous or next, respectively, ARGth node
     in EWOC.  `ewoc-goto-prev' does not move if it is already at the
     first node or if EWOC is empty, whereas `ewoc-goto-next' moves
     past the last node, returning `nil'.  Excepting this special case,
     these functions return the node moved to.

 -- Function: ewoc-goto-node ewoc node
     This moves point to the start of NODE in EWOC.

 -- Function: ewoc-refresh ewoc
     This function regenerates the text of EWOC.  It works by deleting
     the text between the header and the footer, i.e., all the data
     elements' representations, and then calling the pretty-printer
     function for each node, one by one, in order.

 -- Function: ewoc-invalidate ewoc &rest nodes
     This is similar to `ewoc-refresh', except that only NODES in EWOC
     are updated instead of the entire set.

 -- Function: ewoc-delete ewoc &rest nodes
     This deletes each node in NODES from EWOC.

 -- Function: ewoc-filter ewoc predicate &rest args
     This calls PREDICATE for each data element in EWOC and deletes
     those nodes for which PREDICATE returns `nil'.  Any ARGS are
     passed to PREDICATE.

 -- Function: ewoc-collect ewoc predicate &rest args
     This calls PREDICATE for each data element in EWOC and returns a
     list of those elements for which PREDICATE returns non-`nil'.  The
     elements in the list are ordered as in the buffer.  Any ARGS are
     passed to PREDICATE.

 -- Function: ewoc-map map-function ewoc &rest args
     This calls MAP-FUNCTION for each data element in EWOC and updates
     those nodes for which MAP-FUNCTION returns non-`nil'.  Any ARGS
     are passed to MAP-FUNCTION.


File: elisp,  Node: Abstract Display Example,  Prev: Abstract Display Functions,  Up: Abstract Display

38.18.2 Abstract Display Example
--------------------------------

Here is a simple example using functions of the ewoc package to
implement a "color components display", an area in a buffer that
represents a vector of three integers (itself representing a 24-bit RGB
value) in various ways.

     (setq colorcomp-ewoc nil
           colorcomp-data nil
           colorcomp-mode-map nil
           colorcomp-labels ["Red" "Green" "Blue"])

     (defun colorcomp-pp (data)
       (if data
           (let ((comp (aref colorcomp-data data)))
             (insert (aref colorcomp-labels data) "\t: #x"
                     (format "%02X" comp) " "
                     (make-string (ash comp -2) ?#) "\n"))
         (let ((cstr (format "#%02X%02X%02X"
                             (aref colorcomp-data 0)
                             (aref colorcomp-data 1)
                             (aref colorcomp-data 2)))
               (samp " (sample text) "))
           (insert "Color\t: "
                   (propertize samp 'face
                               `(foreground-color . ,cstr))
                   (propertize samp 'face
                               `(background-color . ,cstr))
                   "\n"))))

     (defun colorcomp (color)
       "Allow fiddling with COLOR in a new buffer.
     The buffer is in Color Components mode."
       (interactive "sColor (name or #RGB or #RRGGBB): ")
       (when (string= "" color)
         (setq color "green"))
       (unless (color-values color)
         (error "No such color: %S" color))
       (switch-to-buffer
        (generate-new-buffer (format "originally: %s" color)))
       (kill-all-local-variables)
       (setq major-mode 'colorcomp-mode
             mode-name "Color Components")
       (use-local-map colorcomp-mode-map)
       (erase-buffer)
       (buffer-disable-undo)
       (let ((data (apply 'vector (mapcar (lambda (n) (ash n -8))
                                          (color-values color))))
             (ewoc (ewoc-create 'colorcomp-pp
                                "\nColor Components\n\n"
                                (substitute-command-keys
                                 "\n\\{colorcomp-mode-map}"))))
         (set (make-local-variable 'colorcomp-data) data)
         (set (make-local-variable 'colorcomp-ewoc) ewoc)
         (ewoc-enter-last ewoc 0)
         (ewoc-enter-last ewoc 1)
         (ewoc-enter-last ewoc 2)
         (ewoc-enter-last ewoc nil)))

   This example can be extended to be a "color selection widget" (in
other words, the controller part of the "model/view/controller" design
paradigm) by defining commands to modify `colorcomp-data' and to
"finish" the selection process, and a keymap to tie it all together
conveniently.

     (defun colorcomp-mod (index limit delta)
       (let ((cur (aref colorcomp-data index)))
         (unless (= limit cur)
           (aset colorcomp-data index (+ cur delta)))
         (ewoc-invalidate
          colorcomp-ewoc
          (ewoc-nth colorcomp-ewoc index)
          (ewoc-nth colorcomp-ewoc -1))))

     (defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1))
     (defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1))
     (defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1))
     (defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1))
     (defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1))
     (defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1))

     (defun colorcomp-copy-as-kill-and-exit ()
       "Copy the color components into the kill ring and kill the buffer.
     The string is formatted #RRGGBB (hash followed by six hex digits)."
       (interactive)
       (kill-new (format "#%02X%02X%02X"
                         (aref colorcomp-data 0)
                         (aref colorcomp-data 1)
                         (aref colorcomp-data 2)))
       (kill-buffer nil))

     (setq colorcomp-mode-map
           (let ((m (make-sparse-keymap)))
             (suppress-keymap m)
             (define-key m "i" 'colorcomp-R-less)
             (define-key m "o" 'colorcomp-R-more)
             (define-key m "k" 'colorcomp-G-less)
             (define-key m "l" 'colorcomp-G-more)
             (define-key m "," 'colorcomp-B-less)
             (define-key m "." 'colorcomp-B-more)
             (define-key m " " 'colorcomp-copy-as-kill-and-exit)
             m))

   Note that we never modify the data in each node, which is fixed when
the ewoc is created to be either `nil' or an index into the vector
`colorcomp-data', the actual color components.


File: elisp,  Node: Blinking,  Next: Character Display,  Prev: Abstract Display,  Up: Display

38.19 Blinking Parentheses
==========================

This section describes the mechanism by which Emacs shows a matching
open parenthesis when the user inserts a close parenthesis.

 -- Variable: blink-paren-function
     The value of this variable should be a function (of no arguments)
     to be called whenever a character with close parenthesis syntax is
     inserted.  The value of `blink-paren-function' may be `nil', in
     which case nothing is done.

 -- User Option: blink-matching-paren
     If this variable is `nil', then `blink-matching-open' does nothing.

 -- User Option: blink-matching-paren-distance
     This variable specifies the maximum distance to scan for a matching
     parenthesis before giving up.

 -- User Option: blink-matching-delay
     This variable specifies the number of seconds for the cursor to
     remain at the matching parenthesis.  A fraction of a second often
     gives good results, but the default is 1, which works on all
     systems.

 -- Command: blink-matching-open
     This function is the default value of `blink-paren-function'.  It
     assumes that point follows a character with close parenthesis
     syntax and moves the cursor momentarily to the matching opening
     character.  If that character is not already on the screen, it
     displays the character's context in the echo area.  To avoid long
     delays, this function does not search farther than
     `blink-matching-paren-distance' characters.

     Here is an example of calling this function explicitly.

          (defun interactive-blink-matching-open ()
            "Indicate momentarily the start of sexp before point."
            (interactive)
            (let ((blink-matching-paren-distance
                   (buffer-size))
                  (blink-matching-paren t))
              (blink-matching-open)))


File: elisp,  Node: Character Display,  Next: Beeping,  Prev: Blinking,  Up: Display

38.20 Character Display
=======================

This section describes how characters are actually displayed by Emacs.
Typically, a character is displayed as a "glyph" (a graphical symbol
which occupies one character position on the screen), whose appearance
corresponds to the character itself.  For example, the character `a'
(character code 97) is displayed as `a'.  Some characters, however, are
displayed specially.  For example, the formfeed character (character
code 12) is usually displayed as a sequence of two glyphs, `^L', while
the newline character (character code 10) starts a new screen line.

   You can modify how each character is displayed by defining a
"display table", which maps each character code into a sequence of
glyphs.  *Note Display Tables::.

* Menu:

* Usual Display::       The usual conventions for displaying characters.
* Display Tables::      What a display table consists of.
* Active Display Table::  How Emacs selects a display table to use.
* Glyphs::              How to define a glyph, and what glyphs mean.
* Glyphless Chars::     How glyphless characters are drawn.


File: elisp,  Node: Usual Display,  Next: Display Tables,  Up: Character Display

38.20.1 Usual Display Conventions
---------------------------------

Here are the conventions for displaying each character code (in the
absence of a display table, which can override these conventions; *note
Display Tables::).

   * The "printable ASCII characters", character codes 32 through 126
     (consisting of numerals, English letters, and symbols like `#')
     are displayed literally.

   * The tab character (character code 9) displays as whitespace
     stretching up to the next tab stop column.  *Note Text Display:
     (emacs)Text Display.  The variable `tab-width' controls the number
     of spaces per tab stop (see below).

   * The newline character (character code 10) has a special effect: it
     ends the preceding line and starts a new line.

   * The non-printable "ASCII control characters"--character codes 0
     through 31, as well as the <DEL> character (character code
     127)--display in one of two ways according to the variable
     `ctl-arrow'.  If this variable is non-`nil' (the default), these
     characters are displayed as sequences of two glyphs, where the
     first glyph is `^' (a display table can specify a glyph to use
     instead of `^'); e.g. the <DEL> character is displayed as `^?'.

     If `ctl-arrow' is `nil', these characters are displayed as octal
     escapes (see below).

     This rule also applies to carriage return (character code 13), if
     that character appears in the buffer.  But carriage returns
     usually do not appear in buffer text; they are eliminated as part
     of end-of-line conversion (*note Coding System Basics::).

   * "Raw bytes" are non-ASCII characters with codes 128 through 255
     (*note Text Representations::).  These characters display as
     "octal escapes": sequences of four glyphs, where the first glyph
     is the ASCII code for `\', and the others are digit characters
     representing the character code in octal.  (A display table can
     specify a glyph to use instead of `\'.)

   * Each non-ASCII character with code above 255 is displayed
     literally, if the terminal supports it.  If the terminal does not
     support it, the character is said to be "glyphless", and it is
     usually displayed using a placeholder glyph.  For example, if a
     graphical terminal has no font for a character, Emacs usually
     displays a box containing the character code in hexadecimal.
     *Note Glyphless Chars::.

   The above display conventions apply even when there is a display
table, for any character whose entry in the active display table is
`nil'.  Thus, when you set up a display table, you need only specify
the characters for which you want special behavior.

   The following variables affect how certain characters are displayed
on the screen.  Since they change the number of columns the characters
occupy, they also affect the indentation functions.  They also affect
how the mode line is displayed; if you want to force redisplay of the
mode line using the new values, call the function
`force-mode-line-update' (*note Mode Line Format::).

 -- User Option: ctl-arrow
     This buffer-local variable controls how control characters are
     displayed.  If it is non-`nil', they are displayed as a caret
     followed by the character: `^A'.  If it is `nil', they are
     displayed as octal escapes: a backslash followed by three octal
     digits, as in `\001'.

 -- User Option: tab-width
     The value of this buffer-local variable is the spacing between tab
     stops used for displaying tab characters in Emacs buffers.  The
     value is in units of columns, and the default is 8.  Note that
     this feature is completely independent of the user-settable tab
     stops used by the command `tab-to-tab-stop'.  *Note Indent Tabs::.


File: elisp,  Node: Display Tables,  Next: Active Display Table,  Prev: Usual Display,  Up: Character Display

38.20.2 Display Tables
----------------------

A display table is a special-purpose char-table (*note Char-Tables::),
with `display-table' as its subtype, which is used to override the
usual character display conventions.  This section describes how to
make, inspect, and assign elements to a display table object.

 -- Function: make-display-table
     This creates and returns a display table.  The table initially has
     `nil' in all elements.

   The ordinary elements of the display table are indexed by character
codes; the element at index C says how to display the character code C.
The value should be `nil' (which means to display the character C
according to the usual display conventions; *note Usual Display::), or
a vector of glyph codes (which means to display the character C as
those glyphs; *note Glyphs::).

   *Warning:* if you use the display table to change the display of
newline characters, the whole buffer will be displayed as one long
"line".

   The display table also has six "extra slots" which serve special
purposes.  Here is a table of their meanings; `nil' in any slot means
to use the default for that slot, as stated below.

0
     The glyph for the end of a truncated screen line (the default for
     this is `$').  *Note Glyphs::.  On graphical terminals, Emacs uses
     arrows in the fringes to indicate truncation, so the display table
     has no effect.

1
     The glyph for the end of a continued line (the default is `\').
     On graphical terminals, Emacs uses curved arrows in the fringes to
     indicate continuation, so the display table has no effect.

2
     The glyph for indicating a character displayed as an octal
     character code (the default is `\').

3
     The glyph for indicating a control character (the default is `^').

4
     A vector of glyphs for indicating the presence of invisible lines
     (the default is `...').  *Note Selective Display::.

5
     The glyph used to draw the border between side-by-side windows (the
     default is `|').  *Note Splitting Windows::.  This takes effect
     only when there are no scroll bars; if scroll bars are supported
     and in use, a scroll bar separates the two windows.

   For example, here is how to construct a display table that mimics
the effect of setting `ctl-arrow' to a non-`nil' value (*note Glyphs::,
for the function `make-glyph-code'):

     (setq disptab (make-display-table))
     (dotimes (i 32)
       (or (= i ?\t)
           (= i ?\n)
           (aset disptab i
                 (vector (make-glyph-code ?^ 'escape-glyph)
                         (make-glyph-code (+ i 64) 'escape-glyph)))))
     (aset disptab 127
           (vector (make-glyph-code ?^ 'escape-glyph)
                   (make-glyph-code ?? 'escape-glyph)))))

 -- Function: display-table-slot display-table slot
     This function returns the value of the extra slot SLOT of
     DISPLAY-TABLE.  The argument SLOT may be a number from 0 to 5
     inclusive, or a slot name (symbol).  Valid symbols are
     `truncation', `wrap', `escape', `control', `selective-display',
     and `vertical-border'.

 -- Function: set-display-table-slot display-table slot value
     This function stores VALUE in the extra slot SLOT of
     DISPLAY-TABLE.  The argument SLOT may be a number from 0 to 5
     inclusive, or a slot name (symbol).  Valid symbols are
     `truncation', `wrap', `escape', `control', `selective-display',
     and `vertical-border'.

 -- Function: describe-display-table display-table
     This function displays a description of the display table
     DISPLAY-TABLE in a help buffer.

 -- Command: describe-current-display-table
     This command displays a description of the current display table
     in a help buffer.


File: elisp,  Node: Active Display Table,  Next: Glyphs,  Prev: Display Tables,  Up: Character Display

38.20.3 Active Display Table
----------------------------

Each window can specify a display table, and so can each buffer.  The
window's display table, if there is one, takes precedence over the
buffer's display table.  If neither exists, Emacs tries to use the
standard display table; if that is `nil', Emacs uses the usual
character display conventions (*note Usual Display::).

   Note that display tables affect how the mode line is displayed, so
if you want to force redisplay of the mode line using a new display
table, call `force-mode-line-update' (*note Mode Line Format::).

 -- Function: window-display-table &optional window
     This function returns WINDOW's display table, or `nil' if there is
     none.  The default for WINDOW is the selected window.

 -- Function: set-window-display-table window table
     This function sets the display table of WINDOW to TABLE.  The
     argument TABLE should be either a display table or `nil'.

 -- Variable: buffer-display-table
     This variable is automatically buffer-local in all buffers; its
     value specifies the buffer's display table.  If it is `nil', there
     is no buffer display table.

 -- Variable: standard-display-table
     The value of this variable is the standard display table, which is
     used when Emacs is displaying a buffer in a window with neither a
     window display table nor a buffer display table defined.  Its
     default is `nil'.

   The `disp-table' library defines several functions for changing the
standard display table.


File: elisp,  Node: Glyphs,  Next: Glyphless Chars,  Prev: Active Display Table,  Up: Character Display

38.20.4 Glyphs
--------------

A "glyph" is a graphical symbol which occupies a single character
position on the screen.  Each glyph is represented in Lisp as a "glyph
code", which specifies a character and optionally a face to display it
in (*note Faces::).  The main use of glyph codes is as the entries of
display tables (*note Display Tables::).  The following functions are
used to manipulate glyph codes:

 -- Function: make-glyph-code char &optional face
     This function returns a glyph code representing char CHAR with
     face FACE.  If FACE is omitted or `nil', the glyph uses the
     default face; in that case, the glyph code is an integer.  If FACE
     is non-`nil', the glyph code is not necessarily an integer object.

 -- Function: glyph-char glyph
     This function returns the character of glyph code GLYPH.

 -- Function: glyph-face glyph
     This function returns face of glyph code GLYPH, or `nil' if GLYPH
     uses the default face.

   You can set up a "glyph table" to change how glyph codes are
actually displayed on text terminals.  This feature is semi-obsolete;
use `glyphless-char-display' instead (*note Glyphless Chars::).

 -- Variable: glyph-table
     The value of this variable, if non-`nil', is the current glyph
     table.  It takes effect only on character terminals; on graphical
     displays, all glyphs are displayed literally.  The glyph table
     should be a vector whose Gth element specifies how to display glyph
     code G, where G is the glyph code for a glyph whose face is
     unspecified.  Each element should be one of the following:

    `nil'
          Display this glyph literally.

    a string
          Display this glyph by sending the specified string to the
          terminal.

    a glyph code
          Display the specified glyph code instead.

     Any integer glyph code greater than or equal to the length of the
     glyph table is displayed literally.


File: elisp,  Node: Glyphless Chars,  Prev: Glyphs,  Up: Character Display

38.20.5 Glyphless Character Display
-----------------------------------

"Glyphless characters" are characters which are displayed in a special
way, e.g. as a box containing a hexadecimal code, instead of being
displayed literally.  These include characters which are explicitly
defined to be glyphless, as well as characters for which there is no
available font (on a graphical display), and characters which cannot be
encoded by the terminal's coding system (on a text terminal).

 -- Variable: glyphless-char-display
     The value of this variable is a char-table which defines glyphless
     characters and how they are displayed.  Each entry must be one of
     the following display methods:

    `nil'
          Display the character in the usual way.

    `zero-width'
          Don't display the character.

    `thin-space'
          Display a thin space, 1-pixel wide on graphical displays, or
          1-character wide on text terminals.

    `empty-box'
          Display an empty box.

    `hex-code'
          Display a box containing the Unicode codepoint of the
          character, in hexadecimal notation.

    an ASCII string
          Display a box containing that string.

    a cons cell `(GRAPHICAL . TEXT)'
          Display with GRAPHICAL on graphical displays, and with TEXT
          on text terminals.  Both GRAPHICAL and TEXT must be one of
          the display methods described above.

     The `thin-space', `empty-box', `hex-code', and ASCII string
     display methods are drawn with the `glyphless-char' face.

     The char-table has one extra slot, which determines how to display
     any character that cannot be displayed with any available font, or
     cannot be encoded by the terminal's coding system.  Its value
     should be one of the above display methods, except `zero-width' or
     a cons cell.

     If a character has a non-`nil' entry in an active display table,
     the display table takes effect; in this case, Emacs does not
     consult `glyphless-char-display' at all.

 -- User Option: glyphless-char-display-control
     This user option provides a convenient way to set
     `glyphless-char-display' for groups of similar characters.  Do not
     set its value directly from Lisp code; the value takes effect only
     via a custom `:set' function (*note Variable Definitions::), which
     updates `glyphless-char-display'.

     Its value should be an alist of elements `(GROUP . METHOD)', where
     GROUP is a symbol specifying a group of characters, and METHOD is
     a symbol specifying how to display them.

     GROUP should be one of the following:

    `c0-control'
          ASCII control characters `U+0000' to `U+001F', excluding the
          newline and tab characters (normally displayed as escape
          sequences like `^A'; *note How Text Is Displayed: (emacs)Text
          Display.).

    `c1-control'
          Non-ASCII, non-printing characters `U+0080' to `U+009F'
          (normally displayed as octal escape sequences like `\230').

    `format-control'
          Characters of Unicode General Category `Cf', such as `U+200E'
          (Left-to-Right Mark), but excluding characters that have
          graphic images, such as `U+00AD' (Soft Hyphen).

    `no-font'
          Characters for there is no suitable font, or which cannot be
          encoded by the terminal's coding system.

     The METHOD symbol should be one of `zero-width', `thin-space',
     `empty-box', or `hex-code'.  These have the same meanings as in
     `glyphless-char-display', above.


File: elisp,  Node: Beeping,  Next: Window Systems,  Prev: Character Display,  Up: Display

38.21 Beeping
=============

This section describes how to make Emacs ring the bell (or blink the
screen) to attract the user's attention.  Be conservative about how
often you do this; frequent bells can become irritating.  Also be
careful not to use just beeping when signaling an error is more
appropriate (*note Errors::).

 -- Function: ding &optional do-not-terminate
     This function beeps, or flashes the screen (see `visible-bell'
     below).  It also terminates any keyboard macro currently executing
     unless DO-NOT-TERMINATE is non-`nil'.

 -- Function: beep &optional do-not-terminate
     This is a synonym for `ding'.

 -- User Option: visible-bell
     This variable determines whether Emacs should flash the screen to
     represent a bell.  Non-`nil' means yes, `nil' means no.  This is
     effective on graphical displays, and on text terminals provided
     the terminal's Termcap entry defines the visible bell capability
     (`vb').

 -- Variable: ring-bell-function
     If this is non-`nil', it specifies how Emacs should "ring the
     bell".  Its value should be a function of no arguments.  If this is
     non-`nil', it takes precedence over the `visible-bell' variable.


File: elisp,  Node: Window Systems,  Next: Bidirectional Display,  Prev: Beeping,  Up: Display

38.22 Window Systems
====================

Emacs works with several window systems, most notably the X Window
System.  Both Emacs and X use the term "window", but use it
differently.  An Emacs frame is a single window as far as X is
concerned; the individual Emacs windows are not known to X at all.

 -- Variable: window-system
     This terminal-local variable tells Lisp programs what window system
     Emacs is using for displaying the frame.  The possible values are

    `x'
          Emacs is displaying the frame using X.

    `w32'
          Emacs is displaying the frame using native MS-Windows GUI.

    `ns'
          Emacs is displaying the frame using the Nextstep interface
          (used on GNUstep and Mac OS X).

    `pc'
          Emacs is displaying the frame using MS-DOS direct screen
          writes.

    `nil'
          Emacs is displaying the frame on a character-based terminal.

 -- Variable: initial-window-system
     This variable holds the value of `window-system' used for the
     first frame created by Emacs during startup.  (When Emacs is
     invoked with the `--daemon' option, it does not create any initial
     frames, so `initial-window-system' is `nil'.  *Note daemon:
     (emacs)Initial Options.)

 -- Function: window-system &optional frame
     This function returns a symbol whose name tells what window system
     is used for displaying FRAME (which defaults to the currently
     selected frame).  The list of possible symbols it returns is the
     same one documented for the variable `window-system' above.

   Do _not_ use `window-system' and `initial-window-system' as
predicates or boolean flag variables, if you want to write code that
works differently on text terminals and graphic displays.  That is
because `window-system' is not a good indicator of Emacs capabilities
on a given display type.  Instead, use `display-graphic-p' or any of
the other `display-*-p' predicates described in *note Display Feature
Testing::.

 -- Variable: window-setup-hook
     This variable is a normal hook which Emacs runs after handling the
     initialization files.  Emacs runs this hook after it has completed
     loading your init file, the default initialization file (if any),
     and the terminal-specific Lisp code, and running the hook
     `term-setup-hook'.

     This hook is used for internal purposes: setting up communication
     with the window system, and creating the initial window.  Users
     should not interfere with it.


File: elisp,  Node: Bidirectional Display,  Prev: Window Systems,  Up: Display

38.23 Bidirectional Display
===========================

Emacs can display text written in scripts, such as Arabic, Farsi, and
Hebrew, whose natural ordering for horizontal text display runs from
right to left.  Furthermore, segments of Latin script and digits
embedded in right-to-left text are displayed left-to-right, while
segments of right-to-left script embedded in left-to-right text (e.g.
Arabic or Hebrew text in comments or strings in a program source file)
are appropriately displayed right-to-left.  We call such mixtures of
left-to-right and right-to-left text "bidirectional text".  This
section describes the facilities and options for editing and displaying
bidirectional text.

   Text is stored in Emacs buffers and strings in "logical" (or
"reading") order, i.e. the order in which a human would read each
character.  In right-to-left and bidirectional text, the order in which
characters are displayed on the screen (called "visual order") is not
the same as logical order; the characters' screen positions do not
increase monotonically with string or buffer position.  In performing
this "bidirectional reordering", Emacs follows the Unicode
Bidirectional Algorithm (a.k.a. UBA), which is described in Annex #9 of
the Unicode standard (`http://www.unicode.org/reports/tr9/').  Emacs
provides a "Full Bidirectionality" class implementation of the UBA.

 -- Variable: bidi-display-reordering
     If the value of this buffer-local variable is non-`nil' (the
     default), Emacs performs bidirectional reordering for display.  The
     reordering affects buffer text, as well as display strings and
     overlay strings from text and overlay properties in the buffer
     (*note Overlay Properties::, and *note Display Property::).  If
     the value is `nil', Emacs does not perform bidirectional
     reordering in the buffer.

     The default value of `bidi-display-reordering' controls the
     reordering of strings which are not directly supplied by a buffer,
     including the text displayed in mode lines (*note Mode Line
     Format::) and header lines (*note Header Lines::).

   Emacs never reorders the text of a unibyte buffer, even if
`bidi-display-reordering' is non-`nil' in the buffer.  This is because
unibyte buffers contain raw bytes, not characters, and thus lack the
directionality properties required for reordering.  Therefore, to test
whether text in a buffer will be reordered for display, it is not
enough to test the value of `bidi-display-reordering' alone.  The
correct test is this:

      (if (and enable-multibyte-characters
               bidi-display-reordering)
          ;; Buffer is being reordered for display
        )

   However, unibyte display and overlay strings _are_ reordered if
their parent buffer is reordered.  This is because plain-ASCII strings
are stored by Emacs as unibyte strings.  If a unibyte display or
overlay string includes non-ASCII characters, these characters are
assumed to have left-to-right direction.

   Text covered by `display' text properties, by overlays with
`display' properties whose value is a string, and by any other
properties that replace buffer text, is treated as a single unit when
it is reordered for display.  That is, the entire chunk of text covered
by these properties is reordered together.  Moreover, the bidirectional
properties of the characters in such a chunk of text are ignored, and
Emacs reorders them as if they were replaced with a single character
`U+FFFC', known as the "Object Replacement Character".  This means that
placing a display property over a portion of text may change the way
that the surrounding text is reordered for display.  To prevent this
unexpected effect, always place such properties on text whose
directionality is identical with text that surrounds it.

   Each paragraph of bidirectional text has a "base direction", either
right-to-left or left-to-right.  Left-to-right paragraphs are displayed
beginning at the left margin of the window, and are truncated or
continued when the text reaches the right margin.  Right-to-left
paragraphs are displayed beginning at the right margin, and are
continued or truncated at the left margin.

   By default, Emacs determines the base direction of each paragraph by
looking at the text at its beginning.  The precise method of
determining the base direction is specified by the UBA; in a nutshell,
the first character in a paragraph that has an explicit directionality
determines the base direction of the paragraph.  However, sometimes a
buffer may need to force a certain base direction for its paragraphs.
For example, buffers containing program source code should force all
paragraphs to be displayed left-to-right.  You can use following
variable to do this:

 -- Variable: bidi-paragraph-direction
     If the value of this buffer-local variable is the symbol
     `right-to-left' or `left-to-right', all paragraphs in the buffer
     are assumed to have that specified direction.  Any other value is
     equivalent to `nil' (the default), which means to determine the
     base direction of each paragraph from its contents.

     Modes for program source code should set this to `left-to-right'.
     Prog mode does this by default, so modes derived from Prog mode do
     not need to set this explicitly (*note Basic Major Modes::).

 -- Function: current-bidi-paragraph-direction &optional buffer
     This function returns the paragraph direction at point in the named
     BUFFER.  The returned value is a symbol, either `left-to-right' or
     `right-to-left'.  If BUFFER is omitted or `nil', it defaults to
     the current buffer.  If the buffer-local value of the variable
     `bidi-paragraph-direction' is non-`nil', the returned value will
     be identical to that value; otherwise, the returned value reflects
     the paragraph direction determined dynamically by Emacs.  For
     buffers whose value of `bidi-display-reordering' is `nil' as well
     as unibyte buffers, this function always returns `left-to-right'.

   Bidirectional reordering can have surprising and unpleasant effects
when two strings with bidirectional content are juxtaposed in a buffer,
or otherwise programmatically concatenated into a string of text.  A
typical problematic case is when a buffer consists of sequences of text
"fields" separated by whitespace or punctuation characters, like Buffer
Menu mode or Rmail Summary Mode.  Because the punctuation characters
used as separators have "weak directionality", they take on the
directionality of surrounding text.  As result, a numeric field that
follows a field with bidirectional content can be displayed _to the
left_ of the preceding field, messing up the expected layout.  There
are several ways to avoid this problem:

   - Append the special character `U+200E', LEFT-TO-RIGHT MARK, or LRM,
     to the end of each field that may have bidirectional content, or
     prepend it to the beginning of the following field.  The function
     `bidi-string-mark-left-to-right', described below, comes in handy
     for this purpose.  (In a right-to-left paragraph, use `U+200F',
     RIGHT-TO-LEFT MARK, or RLM, instead.)  This is one of the
     solutions recommended by the UBA.

   - Include the tab character in the field separator.  The tab
     character plays the role of "segment separator" in bidirectional
     reordering, causing the text on either side to be reordered
     separately.

   - Separate fields with a `display' property or overlay with a
     property value of the form `(space . PROPS)' (*note Specified
     Space::).  Emacs treats this display specification as a "paragraph
     separator", and reorders the text on either side separately.

 -- Function: bidi-string-mark-left-to-right string
     This function returns its argument STRING, possibly modified, such
     that the result can be safely concatenated with another string, or
     juxtaposed with another string in a buffer, without disrupting the
     relative layout of this string and the next one on display.  If the
     string returned by this function is displayed as part of a
     left-to-right paragraph, it will always appear on display to the
     left of the text that follows it.  The function works by examining
     the characters of its argument, and if any of those characters
     could cause reordering on display, the function appends the LRM
     character to the string.  The appended LRM character is made
     invisible by giving it an `invisible' text property of `t' (*note
     Invisible Text::).

   The reordering algorithm uses the bidirectional properties of the
characters stored as their `bidi-class' property (*note Character
Properties::).  Lisp programs can change these properties by calling
the `put-char-code-property' function.  However, doing this requires a
thorough understanding of the UBA, and is therefore not recommended.
Any changes to the bidirectional properties of a character have global
effect: they affect all Emacs frames and windows.

   Similarly, the `mirroring' property is used to display the
appropriate mirrored character in the reordered text.  Lisp programs
can affect the mirrored display by changing this property.  Again, any
such changes affect all of Emacs display.


File: elisp,  Node: System Interface,  Next: Packaging,  Prev: Display,  Up: Top

39 Operating System Interface
*****************************

This chapter is about starting and getting out of Emacs, access to
values in the operating system environment, and terminal input, output.

   *Note Building Emacs::, for related information.  *Note Display::,
for additional operating system status information pertaining to the
terminal and the screen.

* Menu:

* Starting Up::         Customizing Emacs startup processing.
* Getting Out::         How exiting works (permanent or temporary).
* System Environment::  Distinguish the name and kind of system.
* User Identification:: Finding the name and user id of the user.
* Time of Day::         Getting the current time.
* Time Conversion::     Converting a time from numeric form to
                          calendrical data and vice versa.
* Time Parsing::        Converting a time from numeric form to text
                          and vice versa.
* Processor Run Time::  Getting the run time used by Emacs.
* Time Calculations::   Adding, subtracting, comparing times, etc.
* Timers::              Setting a timer to call a function at a certain time.
* Idle Timers::         Setting a timer to call a function when Emacs has
                          been idle for a certain length of time.
* Terminal Input::      Accessing and recording terminal input.
* Terminal Output::     Controlling and recording terminal output.
* Sound Output::        Playing sounds on the computer's speaker.
* X11 Keysyms::         Operating on key symbols for X Windows.
* Batch Mode::          Running Emacs without terminal interaction.
* Session Management::  Saving and restoring state with X Session Management.
* Notifications::       Desktop notifications.
* Dynamic Libraries::   On-demand loading of support libraries.


File: elisp,  Node: Starting Up,  Next: Getting Out,  Up: System Interface

39.1 Starting Up Emacs
======================

This section describes what Emacs does when it is started, and how you
can customize these actions.

* Menu:

* Startup Summary::         Sequence of actions Emacs performs at startup.
* Init File::               Details on reading the init file.
* Terminal-Specific::       How the terminal-specific Lisp file is read.
* Command-Line Arguments::  How command-line arguments are processed,
                              and how you can customize them.



Local Variables:
coding: iso-8859-1
End:
